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PREFACE 


This manual describes the BS2000 Data Management System provided for the 
processing of files on magnetic disk. The corresponding description for tape 
files can be found in the "DMS Tape Processing" manual. 


The manual is intended for the BS2000 user who is Looking for information 
concerning file processing. The descriptions of the macro interface and 
access methods are required by the AssembLer programmer. 


e Chapters 1 and 2 contain an overview of the DMS functions. 
e Chapter 3 contains a description of the DMS commands. 
e Chapter 4 contains a description of the DMS macros. 


e Chapter 5 explains the access to files. This chapter also includes a 
description of the service macros. 


e A description of the UPAM, ISAM, SAM and EAM access methods, compLete 
with their action macros, is provided in chapter 6. 


9 The appendix contains information on: 
- conventions 
- DMS DSECTs 
- DMS error codes and error Listing 
- shareable private disk 
- definition of common expressions. 


The amendments and additions that have been made since the previous edition 
of this manual are summarized in the List of Amendments 1, following this 
preface. 


Other manuals are referred to in the text by their abbreviated titles. The 

© full title of each publication mentioned is given at the end of the present 
manual under the heading "Literature". This List also includes the "Druck- 
schriftenverzeichnis" (List of Siemens pubLications) and the "BS2000 System 
Reference Guide". 


To help us continue to improve our publications, please send us your 
comments, requests and suggestions using the pink reply forms provided. 


EditoriaL Department K D ST PH 2 
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LIST OF AMENDMENTS 1 


The following amendments have been made since publication of the 
Revision September 1984 (BS2000 V7. 6A) 3 


and incorporated in the 


Edition November 1985 (BS2000 V8.0A): 


Functions (chapter 2): 


Topic 


Temporary files 


MPVS (Multiple Public 
Volume Set) 
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Amendment 


Temporary files cease to exist as soon as the job is 
terminated (LOGOFF). 

However, they are specified in commands and used just 
Like normal DMS files. 

Temporary files are identified by a prefix in the 
name. 


MuLtipLe public volume sets consist of a number of 
independent public volumes (pubsets) on a single 
system. 

ALL the disks in a pubset are recognized by the 

system as a single unit. 

Pubsets are distinguished by their catalog identifiers 
(catid). 


DMS commands (chapter 3): 


Command 


CATALOG 


COPY 


ERASE 


FILE 


FSTATUS 


IMPORT 


SEC-RES 
SECURE 


SHOW-DEVICE-STATUS 
SHOW-DISK-DEFAULTS 
SHOW-DISK-STATUS 
SHOW-MOUNT PARAMETER 


SHOW-RESOURCE-ALLOCATION 


Amendment 


It is possible to convert a temporary file to a 
permanent fiLe and vice versa. 


By means of the new operand WRITE it is possible to 
specify whether or not an existing file is to be 
overwritten. 


It is possible to erase temporary files and up to 
99 SYSLST files. 


Specification of a temporary file possible. 
New device types: D3480 
D348E 


The new operand FROM enables display from a catalog 
with the specified "catid". 

Symbol specification is possible for the operands 
"Catid" and “filename”. 

In the case of temporary files, the internal file 
name is always specified. 


The REPLACE operand has been extended by the 
specification ABS: 

Importing takes place if the catalog entries have 
the same VSN as the disk to be imported. 

The new operand PVSID defines the catalog which is 
to accommodate the catalog entries. 


As a result of the new device management, the old 
SECURE command has been revised and the new 
SECURE-RESOURCE-ALLOCATION command has been 
introduced. 

This new command provides information on device 
occupancy and volume monitoring. 

vaLues for 


This new command requests the default 


disk parameters. 
disk 


This new command provides information on 


occupancy. 


This new command requests information on mount 


parameters. 


This new command provides information on resource 


allocation and ongoing operator actions. 
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DMS macros (chapters ^ and 5): 


Macro 
CATAL 


COPY 


DSTATUS 


FSTAT 


IMPORT 
RDTFT 


FCB 


Amendment 
Cf. the CATALOG command. 


The nev operand WRITE determines vhether or not an 
existing file is to be overwritten. 


This new macro displays information on the peripheral 
devices. : 


This macro has been brought into Line vith the FSTATUS 
command; the old FSTAT format is retained. 


Cf. the IMPORT command. 
The description of the operands has been revised. 


A nev operand enabLes the specification of options 

Lists: 

GLODEF second attempt to read; 

WARN warning return codes are stored without 
execution being interrupted. 


Error codes CAppendix A.3): 


The error codes vere Listed by means of the IDEMS macro. 
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General 


1 INTRODUCTION 


1.1 POSITION OF THE DMS IN BS2000 


The Data Management System (DMS) is a self-contained component within the 
Control System, alongside the Executive, the teleprocessing system and the 
system services. It serves both the named components of the Control System 
and the users of BS2000. 


The diagram below shows the position of the Data Management System within 
the overall system. 


BS2000 


Control System Problem programs 


Executive 


Language processors 


TeLeprocessing system 


Utility routines 


Fig. 1-1: Position of the Data Management System within the overall system 
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1.2 OVERVIEW OF THE FUNCTIONS OF THE DHS 


The Data Management System offers the user “information containers", called 
files, for storing and retrieving data, as well as a variety of functions 
necessary for working with files: 


e Maintaining files: 
This includes, for example, creating, erasing and copying files, and 
defining protection attributes. 


e Assigning files to programs: 
This includes the option of delaying specification of the files for a 
program until immediately before execution of the program. 


9 Accessing files: 
This includes opening and closing files, and reading from and writing to 
files. 


e Protecting files against unauthorized access: 
This includes checking the access authorization every time a file is 
opened. 


e Managing devices and volumes: 


This includes, for example, reserving and releasing devices and 
requesting volumes (in the case of files on private volumes). 
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1.3 SUMHARIES OF DMS COMMANDS AND HRCROS 


The Data Management System provides the user with a command interface and a 
macro interface. 


Almost all of the functions of the command interface are also available in 
the macro interface. 


However, the macro interface contains additional functions which the command 
interface does not provide (e.g. access to files). 


The following sections provide summarized information on the functional 
scope of the command and macro interfaces. 


- 1.3.1 Commands and Macros for Maintaining Files 


Command | Summary of function 

CATALOG creates or updates a catalog entry. 

COPY copies a file or a file generation group. 
ERASE PONE erases one or more of a user's files. 

FILE FILE defines all attributes of a file and creates 


the catalog entry and an entry in the Task 
File Table (TFT) for this file; reserves 
storage space. 


transfers information from a file's catalog 
entry to the system file SYSOUT. 


FSTATUS 
FSTAT transfers catalog entries in part or in whole 
to a user area (without passwords). 


IMPORT IMPORT creates catalog entries for existing files on 
private disks. 


VERIFY VERIF restores corrupted fives. 
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1.3.2 Commands and Macros for Assigning Files to Programs within a Job 


to which files in the TFT. 


command Summary of function 

CHANGE CHNGE changes the file Link name of a file (in the 
Task File Table, TFT). 

FILE FILE assigns a file Link name to a file and creates 
an entry for this name in the Task File Table 
(TFT). 

RDTFT RDTFT indicates which file Link names are assigned 


1.5.5 Commands and Macros for Managing Private Devices 


Command Macro Summary of function 


RDTFT RDTFT supplies information concerning devices and 
volumes associated with a certain file. 


RELEASE REL reLeases devices. 

SECURE requests resources (files, volumes, devices). 
[ -RESOURCE 

-ALLOCATIONJ 


1.3.4 Macros for Accessing Disk Files 
Preparing access: 


Macro Summary of function 


FCB creates a File Control BLock. 

This controL bLock serves to 

- inform the system which file is to be processed. 

- convey fiLe characteristics to the system (if they 
cannot be taken from an entry in the Task File Table 
or a catalog entry). 

- indicate to the program the current characteristics 
of the file after it has been opened. 


FCBAD generates the code in such a vay that the FCBs may be 
outside the base register in the case of symboLic 
addressing. 

OPEN opens a five. 
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Terminating access: 
Macro Summary of function 
CLOSE closes a specified file or all files open at that time. 
Handling errors and contingencies: 
Macro Summary of function 
EXLST transfers to the DMS addresses at which processing is 
to be continued in the event of errors or task 
contingencies. 
EXRTN returns control to the DMS after executing certain 


EXLST exits and informs the DMS how processing should 
be continued. 


Accessing file contents: 


UPAM 
Macro Summary of function 
PAM passes jobs to UPAM (e.g. Lock block, read block, 


write block, etc.). 
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The following macros are of significance only if UPAM is used in 
conjunction with eventing. Then the underlined macros are mandatory, the 
others optional, according to the problem definition. 

(For a full description of the macros see the "Executive Macros" manual. ) 


ENAEL 
DISEI 


allocates an event item to a user task. 
deallocates a user task from an event item. 
checks the status of an event item. 

sends a request to an event item. 


enables a contingency definition, i.e. allows it to 
control contingency tasks. 


nuLLifies a contingency definition, i.e. prohibits it 
from controlling contingency tasks. 


changes the priority Level of a contingency task or of 
the basic task. 


terminates a contingency task. 
provides read or write access to the register set and 


program counter (the "context") of an interrupted 
contingency task or of the basic task. 


Summary of function 
retrieves the next record from a five. 
writes a record to the end of a file. 


replaces a record previously retrieved by a GET macro 
and updated by the program. 


bypasses the remaining memory area of a buffer. 
enabLes positioning to the beginning of the file or to 


the end of the file, or to the point determined by the 
retrieval address. 
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ISAM 

Macro Summary of function 

ELIM eliminates a record from the file. 

GET retrieves the next record in a file. 

GETFL searches within the specified range for the next record 
which satisfies the flag criteria, and retrieves it. 

GETKY retrieves a record containing the specified key. 

GETR retrieves the next record toward the beginning of the 
file. 

INSRT inserts a record in a file. 

ISREQ cancels a set ISAM Lock. 

OSTAT informs the user about the number of jobs sharing the 
file and the type of shared access (read, write). 

PUT writes a record to the end of a fiLe. 

PUTX replaces a record previously retrieved by a GET, GETFL, 
GETKY or GETR macro. 

RETRY resets the ISAM pointer, after the PGLOCK exit has been 
performed, to the correct position required by a 
following GET, GETR or GETFL macro, and optionally 
repeats the macro which could not be performed because 
of the Locked data bLock. 

SETL enables positioning to the beginning of the file, to 
the end of the file, or to the point determined by the 
key. 

STORE stores a record in the Location determined by the 
specified key. If multiple records with the same key 
are not permitted, the record to be stored overwrites 
any existing record having the same key. 

EAM 

Macro Summary of function 

EAM passes jobs to EAM (e.g. create EAM file, read block, 


write block, close file). 
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1.3.5 Macros for Generating Symbolic Addresses 


Macro 
IDCAT 
IDCE 

IDCEG 
IDCEX 
IDCHA 
IDCOP 
IDECB 
IDEE 


IDEMS 


IDERS 


IDFCB 


IDFST 
IDIMP 
IDMCB 
IDOST 
IDPFL 
IDPFX 
IDPPL 
IDREL 
IDVT 

IDVRF 
DMADR 


DMARD 


for Control BLocks and Operand Lists 


Summary of function 

CATALOG (CATAL) operand List 

Catalog entry 

Catalog entry, addition for file generation groups 
Catalog entry extension 

CHANGE (CHNGE) operand List 

COPY macro operand List 

UPAM event control block 

Catalog entry, extent List 

DMS error messages 

This macro generates a List of EQUs which describes the 
error messages of the DMS modules (cf. Appendix A.3, 
“DMS Error Codes") 


ERASE macro operand List 


FCB (Ρ1 section) 
Note: this DSECT describes all FCB formats. 


FSTATUS (FSTAT) macro operand List 
IMPORT macro operand List 

EAM control block 

File information about opened files of the user 
FILE macro operand List 

FILE macro operand extension 

UPAM operand List 

RELEASE (REL) macro operand List 
VoLume Label entry 

VERIF macro operand List 

Task File Table 


RDTFT macro operand List 
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2 FILES, VOLUMES AND DEVICES IN BS2000 


2-1 FILES 


2.1.1 GeneraL 
Information that is to be processed in a computer must be collected in such 
a way as to produce Logically coherent groups in machine-readable form. 

© The smallest Logical unit is a character (Letter, digit). A number of 
characters form an expression (name, street, tax bracket, bank 


statement). 


Expressions which describe the same object (a specific customer, the required 
spare part, a particular colleague) are combined in a record. 


Several records of the same type which are stored and managed as a single 
unit form a file. 


Every file in BS2000 has a name that distinguishes it unequivocally from all 
other files, and typical dp-specific characteristics such as storage 
structure, access method, type of volume, protection attributes, etc. 

The CPU and the peripheral devices do not know the Logical structure of a 
file. For the sake of the I/O system and the device controllers files are 
divided into transfer units known as blocks. 

A block can contain either exactly one or several Logical records. However, 
a Logical record can also be distributed over several physical blocks if 

the Logical block comprises more than one physical block. 


© Data records consist of a (usually fixed) number of bytes, i.e. 
characters. 


Examples of files: 

- Conventional input/output data used by programs 

- Source programs 

- Module Libraries 

- Textual information to be created and processed by the file editor 
- Command sequences (ENTER and DO procedures) 


= Executable programs 
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How are Logical records stored ina file? 


For storing Logical records in and retrieving them from a file, the DMS 
access methods ISAM and SAM are used (for PAM, a record is the same as a 
block). It should be noted that a file can be processed only using the 
access method it was created with. 


Exception: 
A disk file can be read with the access method UPAM, regardless of which 


access method it was created with. 


What are the different types of file? 
e Permanent files 


Permanent files are cataloged files on external storage media, whose 
names and characteristics are kept by the DMS in the system catalog, and 
which are therefore known to the system. These files thus become resources 2» 
that can be used by more than one job. However, only in special cases 

can a number of parallel jobs write to the same file simultaneously. 


e EAM fivles 


EAM files are stored in the common area SYSEAM and are implicitly deleted 
vhen the job is terminated (LOGOFF). 


e Temporary files 


In contrast to permanent files, a temporary file ceases to exist once the 
job that created it is terminated (LOGOFF). However, temporary files can 
be specified in commands and used just Like normal DMS files (FCBTYPE, 
RECFORM, etc. ). 


Temporary files are defined by a prefix in the file name. This prefix 

can be either of the special characters "#" or "à" and is defined at 

system generation time (class 2 option TEMPFILE). The system administrator 

can provide information on which character has been selected. 

Characteristics of temporary files: 

- Temporary files can be PAM, SAM or ISAM files. 2 


- Temporary files do not belong to the allocated public space, i.e. a 
user with no public space contingent can still create temporary files. 


- As the file names of temporary files are job-specific, there is no 
chance of collision between temporary files with the same name but 
belonging to two different jobs that are active at the same time. 

- In the event of errored system termination, the temporary files of 
the jobs active at the time remain in the catalog, as no LOGOFF can be 
performed. These files are deleted when the pubset is imported (IMCAT 
command). 


- The file names of temporary files must not exceed 31 characters, 
including the special character for the prefix. 


- Temporary files cannot be created on private disk. 


- Temporary file generation groups are not supported. 
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- Temporary files are always created on the user's standard pubset 
under the user's ID. It is neither possible to enter a specification 
under a foreign user ID or vith a non-standard "catid", nor is it 
possible to access temporary files with RFA. 


- Temporary files are kept in the file catalog under an internal file 
name: S.TMP.nnnn. filename (where "nnnn" is the TSN). This internal 
file name is always specified in information commands/macros (e.g. 
FSTATUS, RDTFT), in the ERASE command and in the system messages. 


Note: 


The use of internal file names and their incorporation into programs/ 
procedures eliminates the possibility of portability with other operating 
systems. 

Implementation via a real file with special characteristics is not a 
component of the user interface. 

This can be modified at any time. 


e e Symbolic system files 


These are input and output files which are automatically assigned to 
every user job in BS2000. | 


An example of a symbolic system file is SYSCMD, which is the data source 
from vhich the system takes commands for the associated job. 


Hhich types of fiLes are managed by the Data Management System? 


The DMS manages only cataloged and temporary files, and only processing 
involving such files is described in the present manual. Operations using 
symbolic system files are described in the "Control System Command 
Language" and "Executive Macros" manuals. 


Mapping of files onto voLumes 
The DMS maps files onto volumes. The type of mapping depends on: 
C ® which volumes are used (tape or disk), 


è how a file is to be accessed (e.g. sequential access or indexed 
sequential access). 


The choice of volume therefore immediately Limits the possible modes of 
access. Further details relating to this may be found in the chapter on 
access methods. 


The DMS maintains appropriate tables so that a file mapped onto a volume may 
be reconstructed and its contents accessed at any time. For cataloged files, 
these tabLes are contained in the catalog entry. The tables for temporary 
files are Located in a part of system memory. 
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2.1.2 File Nomenclature 


Each cataloged file has a file name which distinguishes it from all other 
cataloged files. The user ID and the file name form part of the catalog 
entry for this file. 


The user himself must specify the names for his files, and can change them 
as desired. 


Format of the complete file name (path name) 


:catid: $userid. filename 


Files which are not cataloged under the user ID and in the standard pubset 
of the current job must be addressed in the above form (see format F2 for 
an exception). The total Length must not exceed 54 characters. 


: catid: A catalog identifier consists of one character enclosed by 
two colons. | 


userid A user ID consists of a maximum of 8 characters. 
filename A file name can be either fully or partially qualified. 


Possible specifications: 


: catid: Suserid. filename 
: catid: filename 
$userid. filename 
filename 


Fully qualified file names 

A fully qualified file name is the name as it stands in the catalog entry. 
It precisely identifies this catalog entry. 

A catalog entry, in turn, provides a definition of either exactly one file 
or of exactly one file generation group (see section 2.1.6, "File 
Generation Groups"). 


Fully qualified file names can have the following formats: 


Format Fl (format of the file name in the catalog entry) 


absgen 
name1[.name2]...[¢ J 


relgen 


This format designates a file under one user ID and in a pubset. The 
overall Length must not exceed 41 characters. 
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The form of the subnames is as follows: 
name1/name2 Simple names consisting of: 

- At Least 1 Letter (the name in the catalog entry 
contains uppercase Letters only; however, a file name 
can also be entered in Lowercase Letters when input is 
from the terminal). 

- the special characters - (hyphen), a, #, 5. 

The 1st character of a simple name must not be a special 
character; the hyphen must not be its Last character. 
The file name must not consist exclusively of numeric 
characters. 
© absgen An absolute generation number *nnnn, where: 
1 < nnnn ς 9999 


(Leading zeros can be omitted). 


absgen identifies the file generation to other generations 
of the group. | 


relgen A relative generation number 


We 


where: O < nn < 99 
(Leading zeros can be omitted). 


relgen refers to the base value (see section 2.1.6). 
It is derived as follows: 
relgen = absgen - base value. 

C relgen identifies the file generation to the other 
generations of the group. 


Format F2 


$name1. 


This format designates a file under the standard ID to be generated 
(DEFLUID parameter at system generation time). Examples of these files are: 
Language processors, file editors. 


The overall Length must not exceed 44 characters and the name must not 
contain a period. 
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Examples of fully qualified file names: 

SRNO. TEXT. EXAMPLE 

GENERATIONGROUP( *20) 

GENERATIONGROUP(-5) 
PartiaLLy quaLified fiLe names 
A partially qualified file name can identify more than one catalog entry. 
Partially qualified file names can be used only to reference files (or file 
generation groups) which have already been cataloged; they are permitted 
only in certain commands/macros (e.g. ERASE, FSTATUS, PRINT, PUNCH). 


Partially qualified file names have the following format: 
namel. [(name2.]... 


The maximum Length is 39 characters. 


The form of the subname is the same as for fully qualified file names. 


Examples of partially qualified file names: 
$RNO. 
$TSOS. 
PRIM. FORTRAN. 
ALLocation of fiLe names 
When setting up a file, a fully qualified file name must always be 
specified. Where there are a number of Logically associated files, the file 
names can be selected in such a way that, at the same time, 
9 the Logical connection is apparent 
and 
e it is possible to obtain, for instance, status information on all files 
or a printout of all files by means of a single command. 


ExampLe: 


Given the following files: 


SRCE.B. C These files 

SRCE. B. D couLd contain 

SRCE.E source programs. 

OBJ. Y ] These files could contain 
OBJ. Y. Z object modules. 
ENCYCLOPAEDIA This could be a text file. 
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In this case, the command 

PRINT SRCE. | 
will generate a printout of the files 
SRCE.B. C 

SRCE. B. D 


" SRCE. E 


on the printer. 


The command 
FSTAT OBJ. ,ALL 
will cause status information for the files 


OBJ. Y and 


OBJ. Y. Z 


to be displayed on the terminal (SYSOUT). 


Fig. 2-1 illustrates which files are referenced when a partially qualified 
file name is specified. 


Be e 


ENCYCLOPAEDIA 


E B ‘Qualification levels of partially qualified file names 


Fig. 2-1: Relationship between files and file names 


The following should be noted with regard to the allocation of file names: 


Existing (fully qualified) file names can, after further qualification, be 
used as file names for new files, without having to alter the names of the 


existing files. 
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ExampLe: 

The name SRCE.E is further qualified to form the name SRCE.E.ADDITN, which 
could be the name of a file containing additional source program sections. 
SRCE.E continues to identify the same file as before. 


Changing fiLe names 


File names can be changed by means of the CATALOG command. 


ExampLe: 

CATALOG SRCE. E SRCE. FIRST-PROGRAM,STATE-ZUPDATE 

The name of the file SRCE.E is changed into SRCE.FIRST-PROGRAM. 

With disk files (i.e. files on either public or private disks), a file name 

can be changed to any other (fully qualified) file name, with the following 

exceptions: 

- The file name must not already have been allocated. 

- The names of individual generations of a file generation group must not 
be changed. 


In this case, the name change is effected by changing the name for the 
group entry (and thus for all generations at the same time). 


Retrieving fiLes 

To retrieve a file, the DMS has to search for and read the file catalog 
entry. The search process varies according to the vay in which the file name 
was specified: 

e The name was specified using the prefixes ":catid:" and "Suserid. ". 


In this case, the DMS searches for this file solely in the specified 
TSOSCAT under the specified user ID. 


> The file name vas specified with the prefix ":catid:". 
The DMS searches for the file solely under the user ID of the calling job 
and on the specified pubset (provided the caller has a JOIN entry in the 
specified pubset). In the case of an OPEN macro the following applies: 
if the file cannot be found under this user ID, a second read attempt is 
made under the default ID defined by the system administrator (class 2 
option DEFLUID) by specifying OPTION=GLODEF in the FCB macro. 
9 The file name vas specified with the prefix “Suserid. ". 
The DMS searches in the public volume set assigned to the user ($userid). 
ο The file name is specified without a prefix. 
The DMS searches for the file under the user ID of the calling job and 


within the pubset assigned to this user ID, unless OPTION=GLODEF was 
specified in the FCB macro. 
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Special cases: 


- In order to reference files under the default ID defined by the system 
administrator (e.g. EDOR, SORT, ASSEMB) it is sufficient to prefix the 
file name with the character "$". : 


- Whenever an EXECUTE, CALL, DO, ENTER or LOAD command is entered and the 
file name is not explicitly specified with a user ID, the file is always 
sought in a second user ID (default ID). 


ExampLe 1: 

User ID SUSER 
Standard catalog ID C 
DEFLUID TSOS 


CaLL via /EXEC, i.e. a second read attempt is made. 


PVS : A: PVS -ᾱ »ᾱ- 


SUSER. EDOR SUSER. EDT 
: $TSOS. EDOR 


EXEC EDOR File $TSOS.EDOR is found on public volume set C 
EXEC $EDOR File $TSOS. EDOR is found on public volume set C 
EXEC :A:EDOR File SUSER. EDOR is found on public volume set A 


| ExampLe 2: 


The following users are entered in a public volume set: 


- TSOS 
^. DOE 
- SMITH 


- Class 2 option (DEFLUID):  TSOS 
The following files are cataloged for these users: 


TSOS DOE SMITH 


ASSEMB PAYROLL INVENTORY 


FOR1 FOR1 PAYROLL 
ACCOUNT ALGOL 
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The table below illustrates how user references can affect files: 


File referenced by Action 
DOE 
PAYROLL DOE's PAYROLL file accessed 
S$SMITH. PAYROLL SMITH's PAYROLL file accessed, if SHARE=YES 
FOR1 DOE's FOR1 file accessed 
SFOR1 System's FORTRAN compiler accessed 
$TSOS. ASSEMB System's AssembLer accessed 
$SMITH.ACCOUNT Error - SMITH has no file called ACCOUNT 
SALGOL Error - The file is not in the system 


administrator's catalog. 
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2.1.3 Setting Up and Erasing Files 


Setting up files 
The commands 


CATALOG (macro CATAL) 
FILE (macro FILE) 


are used to set up a file. 


The CATALOG command is used to create a catalog entry for a file and to 
define protection attributes for this file, e.g. passwords for read and 
write access. 


However, the technical characteristics of a file set up in this manner are 
Still not defined; neither is any storage space allocated to this file. 


e When the FILE command is used, on the other hand, a Catalog entry can be 
created and storage space reserved. The protection attributes of such a file 
are set to default values; they can be changed by means of a subsequent 
CATALOG command. 


Notes: 


Catalog entries for a user ID are created by the DMS in the order in which 
CATALOG and FILE commands/macros occur. 


When a file is opened and when any other action that necessitates accessing 

a file's catalog entry takes place, the DMS searches the cataLog entries for 
the user ID concerned, one after the other until the required entry is found. 
If many files have been cataloged for this user ID, and if many other entries 
precede the catalog entry required, then searching the catalog is a very 
time-consuming activity. 


To minimize the time required for the search, the following rules should be 
observed when setting up a file: 


e - Catalog as few files as possible for one user ID (e.g. approximately 60 
files). 


- Files which are used most frequently should be Poesy Seen before other 
files. 

Erasing files 

The ERASE command is used for erasing files. 

A file can be erased in the following ways: 

e The file is removed from the system and its storage space released. 
(This is the default function of the ERASE command.) 


The contents of the file can optionally be destroyed before the space is 
released (overwriting with binary zeros). 
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e The storage space is released but the file remains known to the system 
(i.e. it remains cataloged). Here too, the contents of the file can be 
destroyed before the space is released. 


9 The file remains known to the system and the storage space remains 
allocated, but the contents of the file are no Longer accessible (the 
file is “Logically deleted”). 


© The file is removed from the system; its contents, however, remain 
unchanged and the storage space remains allocated. 
Only those files Located on private volumes (tape or disk) can be 
erased in this vay). 


Note: 


In a job, only those files belonging to the user ID under which the job is 
running can be erased. (Exception: system administrator.) 


2.1.4 Relationship between Files and Programs in a Job 


ReLationship based on fiLe names 


A program which has to process a particular file can address that file using 
its fully qualified file name. | 
This procedure has the following disadvantages: 


e The file name must be defined when the program is written. 


e If several different files are to be processed in consecutive program 
runs, the file names of both the file just processed and the next one 
to be processed must be modified in the catalog after every run. 


These disadvantages can be avoided by using a file Link name in place of 
the actual file name for Linking a file with a program in a job. 


ReLationship based on fiLe Link names 
A program can reference every file it is to process by a file Link name. 


Which file is associated with a file Link name in a particular case can be 
defined separately for every program run, so that the file names concerned 
remain unchanged in the catalog. 


The Link between a file and a file Link name applies only to the job in 
which it vas defined. 


The FILE command is used to define file Link names (operands "filename" and 
"LINK-Linkname"). In order to change an existing file Link name, the 
CHANGE command is used. 


The Link between a file and a file Link name for each job is recorded 
internally in the associated Task File Table (TFT). 


If a program wants to open a file during a job and specifies only the file 
Link name, the DMS establishes the relationship to the file for which the 
file Link name specified was defined. 

(For further details see section 5.1, “Opening Files". ) 


It should be noted that software products use predefined file Link names; 
these can be found in the appropriate reference manuals. 
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Example: 

This example illustrates the expediency of file Link names. 

A file DATEI1 is to be sorted using the software product SORT. After 
sorting, the file is to be edited according to certain criteria and output 
on the printer by the user program LISTE. 

The software product SORT employs the following file Link names: 


SORTIN for the input file 
SORTOUT for the output file. 


The user program LISTE uses the file Link name LISTEIN for the input file. 
The problem described above can then be solved using the following command 
sequence: 


/LOGON XYZ 
/FILE DATEI1,LINK=SORTIN The FILE commands establish the 
/FILE DATEI1. SORTIERT,LINK=SORTOUT Link with the file Link names. 
/EXEC SORT 

^ (instructions to SORT) 
/CHANGE SORTOUT,LISTEIN The CHANGE command changes the 
EXEC LISTE file Link name SORTOUT to 
/LOGOFF LISTEIN. 


2eLe-5 File Protection 


Defining protection attributes 


The DMS offers a number of facilities for protecting files against 
inadvertent destruction or unauthorized access. For any of his files a user 
can restrict (by means of the CATALOG command) the number of co-users and 
also the type of access allowed. The owner of a file is considered to be the 
user under whose user ID the file is cataloged. 

In particular, the owner of a file may specify the following: 


5 The system administrator can restrict access to a pubset so that only those 
users explicitly authorized to access the pubset (JOIN entry) can do so. 


9 Access to the file can be restricted to the owner's Jobs, or may be 
permitted for all user jobs (in which case the file is referred to as 
being shareable). 


9 The file can be provided with passwords for read access, write access and 
execution (if the file contains Load modules, object modules or pro- 
cedures). The DMS then permits only those jobs having the appropriate 
passwords to access the file. 


Φ A retention period can be specified for the file, during which the DMS 
does not allow the file to be overwritten, extended or erased. The file 
can be used only as an input file during this period. 


e ALL write access to the file can be prohibited, in which case the DMS 


prevents the file being overwritten, extended or erased. The file can be 
used as an input file only. 
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Notes: 


If no protection attributes are specified when a fil. is set up, the system 
incorporates the following default values: 


- only the owner can access the file 
- no passwords 

- no retention period 

- writing permitted. 


The owner of a file can change the protection attributes at any time (by 
means of the CATALOG command). 


If a file is provided with passwords, these must be specified (by means of 
the PASSWORD command) before the cataLog entry is changed. 


ExampLe: 


User DOE updates the following catalog entries: 


(1) /CATALOG DATEI1,SHARE=NO,ACCESS=READ,STATE=UPDATE 

(2) /CATALOG DATEI2,SHARE=YES,ACCESS=READ,STATE=UPDATE 

(3) /CATALOG DATEIS,SHARE-ZYES,WRPASSzC'Q007' ,STATE=UPDATE 

(4) /CATALOG DATEI4,SHARE=YES,RDPASS=C'1111" ,STATE=UPDATE 

(5) /CATALOG DATEIS,SHAREZYES,RDPASS-C'1111',EXPASS-C'2222' ,STATE=UPDATE 


(191 


Only user DOE can access the file DATEI1. Not even DOE, the owner, can write 
to the file while write access is forbidden (ACCESS=READ). 


(2): 
ALL users of the system can read S$DOE.DATEI2. 
(3): 


ALL users of the system can read $DOE.DATEI3. Only those users who 
specify the password C'007' have write access. 


(4): 3 


OnLy those users who specify the password C'1111' can read or write in 
SDOE. DATEI. | 


(5): 


Users who omit both passwords can neither read nor execute the file. 

If a user specifies the execution password, he can execute the file, but 

not copy it. 

If he also specifies the read password, he is able to read the file and even 
overwrite it. 


Access to password-protected fiLes 

If a job wishes to access a file protected by passwords, it must specify 
the passwords necessary for that access, using one of the two following 
methods: | 

èe with a PASSWORD command (any number of passwords). 


The passwords given in this vay are placed in the job's password table, 
and do not therefore need to be entered anew for every access. 23 
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e With the FCB macro, used when the file is opened (only one password 2 
permitted). 


Passwords have the following order of priority: 

- execute password (highest priority) 

- read password 

- write password (Lowest priority). 

This means that each password also has the function of the Lower priority 
passwords. This extended protection is rendered ineffective if the password 


with the Lover priority is explicitly specified. The following table shows 
“which passwords should be specified to obtain the access required. 


Key: 
© E = Execute the file contents (EXEC, LOAD, DO, ENTER commands). 
R = Read the file (OPEN mode INPUT). 
W = Write the file or change the catalog entry (OPEN modes OUTPUT, OUTIN, 


INOUT; CATALOG command; FILE command with SPACE operand. 


The gray shaded areas in the upper part of the table indicate that the 
password in the Left-hand column of the table is cataloged. 


Desired access 


Execution password 
cataloged 


Read password 
cataloged 


Write password 
cataloged 


Execution password 
required 


Read password 
required 


Write password 
required 


Table 2-1: Password specification requirements in relation to the 
desired type of access 
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System administrator and file protection 


The system administrator is the only user who has privileges over other 
users with regard to accessing files. 


The system administrator can obtain information relating to the protection 
attributes of any file entered in the system catalog, and if necessary modify 
these attributes. This facility is necessary to ensure the smooth running of 
the system. For example, if a user should forget the passwords for his file, 
the system administrator can read out the passwords, or, in the case of 
systems with coded passwords, can delete the passwords so that the file once 
more becomes accessible for the user. 


As a rule, the system administrator has access to every file entered in the 
system catalog, regardless of the owner. 


Protection mechanisms for multiple jobs simultaneously 
accessing one file 


In addition to file protection by means of catalog attributes, the DMS also 
provides mechanisms which prevent the mutual interference of jobs wishing 
to process the same file simultaneously. 


As a rule, the DMS does not permit more than one job to operate with the 
same file. The following are the exceptions to this rule: 


e Several jobs can simultaneously access one file if each individual file 
wishes only to read it. 
(The protection attributes of the file are, of course, still observed. ) 


e In the case of the access methods UPAM and ISAM (see chapter 6, "Access 
Methods"), the DMS provides the "shared file update" function, which 
allows multiple jobs to read into and write from a file simuLtaneousLy. 
To prevent interference between jobs, parts of a file can be Locked 
temporarily by a job. These parts cannot be accessed by other jobs until 
they are unlocked by the Locking job (mutual exclusion). { 


2.1.6 File Generation Groups (FGG) 


General 


A file generation group (FGG) is a collection of cataloged files -- the 
generations -- with the following characteristics: 


® The order in which the individual generations are created (the 
chronological sequence) remains known to the system. This is effected 
by means of the allocation of a consecutive number (the absolute 
generation number) to each one. 
Each absolute generation number corresponds exactly to a position in the 
chronological sequence; the "Less than/greater than" relationship between 
two absolute generation numbers represents the chronological relationship 
"older/newer™ between generations. 


Exception: 
If the absolute generation number of a generation is 9999, the 


successor generation is given absolute generation number 1. 
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ExampLe: 


File generation group structure 


Oldest | Youngest 
generation generation 


e Fig. 2-2: File generation group structure 


e Each generation can be addressed by a relative generation number. The 
user himself can select the point of reference for relative numbering, 
but should first ensure that the generation selected as the point of 
reference is cataloged (see also the subsection "Changing the relationship 
between relative and absolute generation numbers" below). 


Example: 


Relationship between relative and absolute generation numbers 


Absolute 
generation eee* 
number 


Relative 
generation eee 
number 


Generation 21 is the current reference point for relative numbering 
se 
Ri 
] :Signifies that the catalog has not yet been cataloged 
Eg 


( 
\ 


Fig. 2-3: Relationship between relative and absolute generation numbers 
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e Catalog characteristics, such as shareability, read or write access, file 
passwords etc. apply equally to all generations. 
They are characteristics for the file generation group as a whole. 


File generation groups are particularly suitable for regularly recurring 
jobs, such as customer master file updating, invoicing etc. 


The user of relative generation numbers dispenses with the need to 
formuLate the job prior to processing. 


In addition, file generation groups offer a convenient method of data 
saving, according to the grandfather-father-son principle. 


PROCESSING OF FILE GENERATION GROUPS 


Setting up file generation groups 


The system manages file generation groups by means of a catalog entry (the 
group entry), which differs from a normal entry for a file, and which can 
be created only by means of a CATALOG command/macro. 


In order to create the group entry, the CATALOG command/macro must contain 
the following: 


€ the group name (operand “filename1") and 

€ the maximum number of generations to be maintained in the catalog 
(operand GEN=) 

The group name must differ from all already cataloged file names. 


In addition, the following specifications can be included in the group entry 
regarding: 


ə file protection (operands ACCESS=, SHARE=, RDPASS= etc.). These 
specifications normally apply globally to all generations. 


However, when working with private volumes (EXPORT/IMPORT) the user must 
ensure that generations with different protection attributes do not arise 
as a result of a CATALOG command. 


Exception: 


The catalog attributes of the group were modified at a time when one or 
more groups were unavailable (message DMSOGA9: GENERATIONS OF THE FGG 
MISSING). 


If the user wishes to restore the normal status, he must issue a further 
CATALOG command/macro in order to update the FGG with the desired catalog 
attributes. This then causes the catalog entries of all associated 
generations to be updated. 


The determining factors for file access to an FGG are the attributes 
defined in the catalog entry of the FGG. 
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e the procedure to be adopted when the maximum number of generations 
allowed in the catalog has been reached (operand DISP=). It is possible 
to specify that, in this case, the oldest generation is to be deleted 
upon cataloging the newest (either with or without reusing the private 
volumes used by the deleted generation), or that all generations are to 
be simultaneously deleted or retained. 


Upon recataLoging the group entry of existing file generation groups on 
private volumes, one of the following specifications must additionally be 
made, regarding: 


e the chronological order (for tapes). Specify 
- the oldest generation to be held in the catalog (operand FIRST=), and 


- the base generation to be used as a reference point for relative 
numbering (operand BASE=). 


e Otherwise, the group entry is to be generated in the same vay as any 
new catalog entry (operands STATE-NEW, GEN=). 


e the device and the volume serial number (for disks). The operands 
STATE=FOREIGN, DEVICE=, VOLUME= are required in order to transfer the 
group entry from the F1 Label to the catalog. 

Example 1: 

A file generation group GROUP1 is to be set up on public volumes. 

The maximum number of generations to be held in the catalog is to be set 

at 5. When this number is reached, the oldest generation is to be deleted. 

The file generation group is to be shareable. 

These attributes are defined in the group entry by the following command: 


/CATALOG GROUP1,GEN=5,DISP=CYCLE,SHARE=YES,STATE=NEW 


Example 2: 
e A file generation group GROUP3 on private disks is to be recataLloged. 
In this case, the group entry must be read from the F1 Label and pLaced in 
the catalog. 
This is achieved by means of the following command: 


/CATALOG GROUPS,STATE-FOREIGN,DEVICE-D3455,VOLUME-DSKO11 
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Creating generations 


Generations of. an FGG are always created using the FILE command/macro or, if 
only the catalog entry is to be created, with the CATALOG command. 

A generation name with absolute or relative generation number must be 
specified. 


Note: 


When creating generations for the same FGG, the generation numbers used in 
the generation name must satisfy the following conditions: 


Absolute generation numbers ReLative generation numbers 


must not be used multiply. must not be used multiply within 
one job. For an exception, refer 
to "Changing the relationship 
between relative and absolute 
generation numbers" below. 


must be greater than zero. must be specified with the sign 
"Q4. 7 or "n. 


The resultant absolute generation numbers must always be in ascending 
sequence, and there must always be a difference of 1 between two absolute 
generation numbers created one immediately after the other, i.e. there must 
be no gaps. 


(See the CATALOG and FILE commands for a description of the format.) 


Example 3: 
Creating generations of file generation group GROUP1 on public volumes 


/FILE GROUP1(+1),LINK=OUT1 

/FILE GROUP1(-*2) ,LINK-OUT2 

/FILE GROUP1(+4) ,LINK=OUT3 

*DMSO6BC7 USER ATTEMPTED TO PROCESS A GENERATION WITH AN INCORRECT 
GENERATION NUMBER. COMMAND TERMINATED. 

(Generations must be created consecutively without gaps, hence) 
/FILE GROUP1( +3) ,LINK=OUT3 


Notes: 


ALL generations of an ΕΟΟ on public volumes must be on the same pubset, i.e. 
all generations of an FGG have the same catalog ID. 


The following restrictions apply for: 


- file generation groups stored on private volumes. 
If a file generation group stored on private volumes is known to a system, 
it must be cataloged in its entirety on one pubset, i.e. including all 
existing generations. Such an FGG can also be cataloged in more than one 
pubset; however, in this case it must be cataloged in its entirety in 
every pubset. 


- file generation groups stored on public volumes. 


These FGGs must be contained in their entirety on one pubset, i.e. 
including all existing generations. 
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Deleting generations 


The same applies when deleting generations as when creating them, in that 
^o gaps must occur in the sequence of the absolute generation numbers. 
Thus, starting from any arbitrarily selected generation, only all older 
or all newer generations can be deleted (operand POS= in the ERASE 
command/macro). 


If the previous base generation for relative generation numbers is deleted 
by an erase operation, the generation specified in the ERASE command/macro 
becomes the new base generation. 


An erase operation always updates at Least one of the fields in the group 
entry, which contain the absoLute generation numbers of the oLdest and 
newest generations entered in the catalog. This is not the case when only 
the catalog entries of generations on private volumes are deleted. 


e Note: 


Gaps may occur in a file generation group when using the ERASE command with 
the operands CATALOG and VOLUME=vsn for private disks; see also the note 


for the IMPORT command. 


Example 4: 
File generation group GROUPS has the following form: 


Fige 2-4: Form of GROUPS 


Taking generation 3 as the base, all older generations are to be deleted. 
This is done using the following command: 


ERASE GROUPS(+0) ,POS=BEFORE 
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After execution of this command, GROUPS has the following forn: 


Fige 2-5: Form of GROUPS 


If generation 3 is also to be deleted, this can be achieved by the following 
command: 


/ERASE GROUPS(*4) ,POS=BEFORE 


After execution of this command, GROUPS has the following form: 


Πα. 


Fig. 2-6: Form of GROUPS 


Since the previous base generation for relative numbering has been deleted, 
the relationship between relative and absolute generation numbers had to be 


redefined. i^ 


Changing the reLationship between ο “ον and absolute 
generation numbers 


It is possible to change the relationship between relative and absolute 
generation numbers during a job by means of a CATALOG command (operand 
BASE=). The group name must be specified, as well as the generation which is 
to serve as the new reference point for relative generation numbers. This 
generation is identified by an absolute or relative generation number. Only 
a generation which has already been cataloged may be selected as the new 
reference point for relativization. 
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Note: 


In this case, the reference point for relative generation numbers is the 
newest generation at this point in time, and may therefore differ from the 
newest generation at the time of job initiation. This always applies when 
new generations have been created during the course of the current job. 


ExampLe 5: 


File generation group GROUPS has the following form: 


Fig. 2-7: Form of GROUPS 


The command 


/CATALOG GROUP6,BASE=-2,STATE=UPDATE 


defines the following relationship: 


Fig. 2-8: Form of GROUPS 
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Volumes for file generation groups 


File generation groups can be created and processed on public and private 
volumes. 


Notes: 
e The mixed use of public disks and tapes is permitted. 


e The use of private disks for an FGG precludes the use of other volumes 
for that FGG. Device and volume specifications must be made when creating 
the group entry and the generations (operands DEVICE- and VOLUME= in the 
CATALOG command). 


In extreme cases, a separate volume can be provided for each 
generation. 


e If a file generation group which exists on private disks but has not been 
cataloged is to be recataLoged, the following procedure must be used: 9 


- The group entry is to be created as described under "Setting up file 
generation groups”. 


Subsequently, at Least those generations which occur between the 
oldest generation maintained in the catalog and the base generation 
for relative numbering (inclusive) are to be cataloged, using one 
FILE command for each generation. 


The FILE commands must contain the operands STATE=FOREIGN and DEVICE= 
and VOLUME=. 


- The IMPORT command provides a further facility for cataloging the file 
generation group, but certain special conditions must be observed. 
See also the IMPORT command. 


Example 6: 


ALL generations of file generation group GROUP3 which are contained on 
private disks are to be recataloged (see Example 2). 


GROUP3 consists of the following generations: 


Generation 1 DSKOO05 
Generation 2 on DSKOO3 
Generation 3 voLume DSK150 
Generation 4 DSK150 


The volumes are already mounted on 3455 Disk Storage Units. 
The following commands will effect cataloging of the generations: 


/FILE GROUP3(*1) ,LINK=DZ1,DEVICE=D3455, VOLUME=DSK006,STATE=F OREIGN 
/FILE GROUP3(*2) ,LINK=DZ2,DEVICE=D3455, VOLUME=DSK003,STATE=F OREIGN 


/FILE GROUP3(*3) ,LINK=DZ3,DEVICE=D3455, VOLUME=DSK150,STATE=F OREIGN 
/FILE GROUP3(*4) ,LINK=DZ4,DEVICE=D3455, VOLUME=DSK150,STATE=F OREIGN 
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Reserving file generation groups 


A file generation group (including all generations) can be reserved for a 
job by specifying the group name and the operand EX in the SECURE command. 
The reservation does not cover the volumes; it merely prevents another gob 
from accessing the FGG or one of its generations (by means of a Lock in the 
File Lock Table, FLT). 


Note: 


Simultaneous accessing of one FGG by multiple jobs can Lead to 


unpredictable results. 


It is therefore always advisable to make use of the reservation facility in 
cases where simultaneous accessing of one FGG by multiple jobs cannot be 
ruled out. 


Example 7: 


File generation group GROUPS is being processed by job 1 and has the 
following form: 


Fige 2-9: Form of GROUPS 


At this moment, job 2 is started. This creates generation 7, erases 
generation 4 and is then terminated. 


GROUPS now has the following form: 


Fige 2-10: Form of GROUPS 
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The use of relative generation numbers will always result in the wrong 
generation being accessed. 


If GROUPS(*0) is specified, job 1 will nov address generation 7 and not the 
desired generation 5. 


Even if absolute generation numbers are used, an error will occur as soon 
as the extinct generation 4 is referenced. 


Non-executability of generations 


The generations of an FGG are not executable files. Thus, there is no point 
in using them to store 


€ ENTER/DO procedures or 
è Load and object modules 


Support of fiLe generation groups by utiLity routines or 
software products 


File generation groups are not supported by all utility routines or software 
products. 


Non-supporting routines and software products are: 


AUPMAIN (for system administrator only) 
LMS 

PRSERVE 

TSOSLNK. 


2.1.7 Restoration of Corrupted FiLes 


If processing of a file is terminated abnormally (the job processing the 
file, referred to below as the "processing job", is terminated, e.g. due to 
a system failure, or it is deactivated until the end of the session, e.g. 
due to memory saturation), the file may be inaccessible for subsequent 
processing. 


This is due to the following reasons: 
e The file Lock imposed by the processing job has not yet been removed. 


9 The file contents and parts of the catalog entry (e.g. the pointer to the 
Last PAM bLock in the file) are inconsistent. 


e With ISAM files there may also be disparities in the relationships 
between file data section and file index section. 


By using the VERIFY command (VERIF macro), it is possible to restore files 
corrupted in this way so that normal processing may continue. 

In the program a branch can be made to an error routine via the EXLST exit 
OPENC (cf. section 5.4). 

The FSTATUS command (FSTAT macro) can be used to determine which files have 
not been closed, e.g. as the result of a system failure (see the operand 
STATE=NOCLOS). 
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Restoring corrupted files 


e The file must be unlocked if it is still Locked (remove the entry for 
this file in the File Lock Table, FLT). 


However, a check is made as to whether the Lock is not in fact stiLL 
required. : 


The Lock is removed only if 


- the file was Locked by a SECURE command and the processing job is in 
a constantLy inactive state or 


- the file is a tape file and the processing job is in a constantly 
inactive state. 


With disk files that were not Locked by a SECURE command, only the system 
administrator can remove a Lock. 


e e Disk files which have already been unlocked are handled differently 
according to the access method used to create then: 


- In the case of an SAM file, the pointer in the catalog entry is 
changed so as to indicate the Last PAM bLock of this file (with normal 
file processing, this pointer is not set until the file is closed). 


The file can then be reopened (also in EXTEND mode, if required). 


It now also becomes possible once more to access the Last records 
placed in the file. However, records which were being processed in the 
buffer immediately prior to job termination might be Lost; see also 
"Limitations on file restoration" below). 


~ In the case of an ISAM file, all records which can still be restored 
are written to an ISAM restoration file with new key blocks. 


It is possible to specify the file name under which the restored file 
is to be stored (operand "fiLename2" in the VERIFY command/VERIF 


macro). 
© If this file is contained on private disks, it must already have been 
provided with sufficient storage space. If a user-suppLied file is 


used for restoration, the corrupted file is not erased. 


If no second file name is specified, the corrupted file is restored in 
a work file (on public volumes). 


If the corrupted file is on 
* private volumes, it is overwritten by the contents of the work file. 


The work file is subsequently deleted (and its data is destroyed 
for file security reasons). 


* public volumes, it is deleted (without data destruction, in order 


to save time) and the work file receives the name of the original 
file. 
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- In the case of a UPAM file, a privileged close operation is performed. 
If necessary and possible, the file is unlocked. Subsequently the 
pointer is updated so as to point to the Last PAM block (LPP) of this 
file. This ensures that none of the blocks containing data are 
released in the event of a subsequent FILE command/macro with a 
negative SPACE specification. 


The restoration of a UPAM file and simultaneous updating of the LPP 
are initiated via the VERIFY command (VERIF macro) and the operand 
REPAIR-ABS. 


Note: 

This function requires that a file is opened and then read backwards 
until the current PAM page is reached. Consequently, it can be very 
time-consuming in the case of Large files. 


Restoring corrupted fiLes under a foreign user ID 


If a foreign user ID is specified in a path name, the file must be cataloged 
as shareable. 


If no other file was specified, a scratch file is created under the user's 
own ID. After restoration, this scratch file is copied into the original 
file and deleted by means of ERASE,DESTROY. If a third file is required, it 
too is created under the caller's user ID. As the scratch files are 
initialized in the disk set containing the file to be restored, the caller 
must have access authorization for the disk set of the specified file. 


Limitations on fiLe restoration 


e As a result of the buffering in main memory of Logical records from SAM 
and ISAM files, changes made immediately prior to termination of file 
processing might be Lost. 


With ISAM files, this problem can be overcome by immediately writing back 
to the volume (operand WROUT=YES in the FILE command). It should be 
noted, however, that this process increases overall time expenditure. 


® When restoring ISAM files, if any duplicate records are involved (i.e. 
records with identical keys and identical data), only one such record 
is included in the restoration file in each case. 


This restriction is required to permit the restoration of ISAM files 
whose processing was terminated during a block splitting operation. 


€ ISAM files with separate volumes for file index section and file data 
section can be restored only if the size of the data blocks is one 
PAM block. 


e If a data block of an ISAM file cannot be restored (e.g. due to the 
accidental destruction of internal file pointers, or because an updated 
muLti-bLock buffer could be only partially written back to the volume), 
the block is written to a special PAM file. 

This PAM file is available to the user after completion of reconstruction 
for his own restoration needs. 


The file name is as follows: 


S. filename-corrupted-file. REPAIR 
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e If a corrupted ISAM file contains multiple records with identical keys 
(but different data), the sequence of these records in the restoration 
file may differ from the original order. 


e With the restoration of ISAM files, no free space is Left in the data 
blocks for subsequent additions (the value of the PAD operand in the FILE 
command is ignored). 


e The time factor involved in the restoration of ISAM files should not 
be ignored. 


It can increase considerably in the case of files on private volumes if 
the user does not supply a restoration file (already provided with 
sufficient storage space). (See the operand "fiLename2" in the VERIFY 
command/VERIF macro.) 
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2.2 VOLUMES 


2.2.1 PubLic and Private VoLumes 


In BS2000, there are two different types of volume: 


pubLic voLumes 
private volumes. 


Only disks can be pubLic volumes. Private volumes are all tapes and all 
disks not marked as public volumes. 
Both types of volume can be used together. 


When defining disks, the DMS distinguishes between two different types: 


‘PYS (pubLic volume sets) 


private disks. 


A PVS consists of one or more public volumes. The system itself, together 
with a number of other files which it needs, is stored on a PVS known as 


the "home pubset", which is available throughout the session. 


need not be made available until actually required (as also applies to 
private volumes). 


The DMS assumes responsibility for memory management on disks and 
guarantees full data protection for all volumes. In this case certain 


check functions (access authorization, saturation control, etc.) apply only 


to pubsets and not to private disks. 


2.2.2 Space Management (Disks) 


£m S 


In the case of primary allocation, memory space is allocated to a file 
for the first time, and a catalog entry is created. 


Whenever possible, the system assigns contiguous space, and arranges even 


distribution over the public volumes empLoyed. 


With secondary allocation, additional space required by a.file is 
allocated. 


This procedure can be repeated as Long as the total amount of space 
available to the user ID has not been exhausted (see also the next 
section, "Requesting public and private volumes"). 

Dividing a file between several volumes should be avoided if possible. 
Storage space is allocated in the following units: 

- unit (= 3 PAM bLocks) 

- packet (= 8 units = 24 PAM blocks) 

- segment (= 8 packets = 64 units = 192 PAM blocks). 


The user can adapt primary and secondary allocation to his particular 
requirements by way of the SPACE operand in the FILE command. 


Other pubsets 
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^ If the system is unable to fulfil a request for space, the following 
occurs: 


- Either the FILE command issued for a primary allocation is rejected, 
or the request for space is honored in part. 


- In the case of a secondary allocation, control passes to the NOSPACE 
exit (see the EXLST macro). 


e Grounds for the non-aLLocation of storage space on public volumes: 


- At the time the request vas made, saturation of the relevant pubset had 
reached Level 4, or would have done if the allocation requested had 
been granted. ! 


The procedure for this eventuality can be defined at system generation 
time (class 2 option): 


6 * the request is rejected immediately, or 


* the operator decides whether to accept or reject the allocation 
request. 


The allocation of storage space for a pubset is controlled via 5 
saturation Levels. On Levels 1 (Lowest saturation Level) through 3 
all allocation requests are accommodated, memory bottlenecks being 
indicated by messages at the console. 


On saturation Level 4, jobs requesting memory space are placed in a 
queue until a Lower saturation Level has been reached. 


On Level 5 (highest saturation Level), only system administrator jobs 
may request memory space; requests from other jobs are rejected. 


Note: 

Saturation Levels 4 and 5 must be avoided for the home pubset (by 
means of deleting files that are no Longer needed or that cannot be 
restored) in order to avoid endangering a renewed startup. 


- If the request were satisfied, the user would occupy more space on the 
- relevant pubset than is at his disposal. 


- The request exceeds the upper Limit on public space available for the 
user ID under which the job is being executed. 


ο Grounds for the non-allocation of storage space on private volumes: 


- The capacity of the volume(s) has been exhausted, and thus no further 
space allocation is possible. 


, £^ 


U805-J-Z255-5-7600 231 


Volumes 
2.2.5 Management of Public and Private Volumes 


Requesting public and private volumes 


9 A request for space on public volumes is effected by means of the FILE 
command. 


By means of the "catid" specification the user can determine the pubset 
on which space is to be allocated, but he cannot influence the choice 
of the disks on which he is allocated space (if the pubset consists of 
more than one disk). However, he can request information on the success 
or otherwise of the allocation by using the FSTATUS command/FSTAT macro 
or the DCAT utility routine. 


Each pubset contains the following information: 


- the users who are authorized to access this pubset are specified; 
other users have no access authorization; 9 


- an upper Limit is defined for every user with access authorization; 


- those users with access authorization who may exceed this upper Limit 
are specified. 


Users who are not authorized to access a pubset cannot request memory 
space on this pubset. 


A user with access authorization may request space until he has reached 
the upper Limit defined for him. If he is authorized to exceed this 
Limit, he may continue to request space. 

The operator receives a message informing him that a certain user has 
exceeded his prescribed Limit. If the user has still exceeded his 

Limit at LOGOFF, he receives a message to this effect. 

The storage Limit is set by the system administrator. The user can 
request information on this Limit by means of the command /ACCOUNT or 

/ SHOW-USER-ATTRIBUTES. 


e Requests for private space or private volumes are effected by a FILE 9 
command/macro. 


A private volume or device is made available for the duration of the 
requirements of the jobs concerned. 


Space on private disks can be requested in any quantity (Limited only by 
the capacity of the volume). 


In addition, the following may be specified: 
- the volume(s) on which space is to be reserved, and 
- which physical blocks are to be reserved. 


(See also the operands VOLUME= and SPACE= in the FILE command. ) 
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Operating modes for private voLumes 
A private file can be used: 
- exclusively by one job. 
- jygointly by a number of jobs executing simultaneously. 
The desired operating mode is specified by the operator. 
If a file extends over several private disks, all the volumes must be 
mounted at OPEN time. 
Releasing private volumes 
Private volumes and devices are released when one of the following 
conditions applies to all jobs concerned: 
- - LOGOFF 
- RELEASE 
LT S serves to release the devices and volumes allocated to a 


-  SECUREL-RESOURCE -ALLOCATIONJ 
Specifying the SECUREL-RESOURCE-ALLOCATION] command vithout operands, or 
requesting further volumes or devices, means that all those previously 
reserved are released in order to avoid deadlock situations. 


- WHEN 
ALL devices and volumes are returned to the system, as this command can 
be used to deactivate a job and place it in the job queue. 


- Abnormal termination of job. 


Use of private volumes belonging to another computer center 


The private disks of one BS2000 computer center can be used in other 
© 3S2000 computer centers. 


Notes: 


A file on a private disk can be transferred to another system only if the 
owner's user ID is entered in the other system. 
This applies whether the file is transferred by the owner himself or by 
the system administrator. 
Exception: If IMPORT with NUSERID=new userid is specified by the system 
administrator, the old user ID need not still exist (see the "System 
Administrator's Guide" manual. 
In both cases the file to be transferred is cataloged under the user ID of 
the owner; the DMS takes the file attributes from the F1 Label of the 
volume, not from a FILE command or from an existing catalog entry. 
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- Transfer to the other system can be effected in the following ways: 


(1) An IMPORT command can be used if more than one file is to be 
transferred. This command also processes partially qualified file 
names. 


(2) Transfer of a single file can be effected by means of a FILE command 
containing the following operands: 


filename 
STATE=FORELGN 
VOLUME=vsn 
DEVICE=device 


If the file is to be transferred under the system administrator's 
ID, the file name should be prefixed by the owner's user ID. 


(3) Catalog entries can be saved in the source system and created in 
the target system by means of the RECAT utility routine. 


Information on the use of tapes from other computer centers in a BS2000 
computer center can be found in the "DMS Tape Processing” manual. 


Pool monitoring (MVDF) 


The total number of private disks of a computer center is divided into 
pools. 

The whole file must belong to a single pool and must be Located on this 
pool. In other words, the areas of the file extend over private disks that 
all belong to the same pool. 

The pool affiliation of a disk is entered in the SVL. Formation and admin- 
istration are performed by means of the PDPOOLS utility routine (see the 
"System Administrator's Guide™ manual). 


This arrangement permits sets of files Lost as a result of disk crashes to 
be restored without any problems. 


A check is performed at the following stages (arranged in descending order 
of importance): 


- Creation and static extension of a file (FILE command) 9 


- Opening a file (OPEN) 
- Dynamic extension of an opened file. 
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2.4 MPVS 


MPVS (Multiple Public Volume Set) supports several independent sets of 
public disks on a single system. These sets are referred to in this manual 
as "pubsets". 


The creation of MPVS represents an attempt to combine the advantages of 
public and private disks, the most notable improvements being the following: 


Distribution of a Large disk pool comprising severaL disks over a numbe 
of small pubsets each consisting Of a fev disks; this means that the si 
of a pubset to be restored in the event of an error can be Limited vith 
sacrificing the performance advantages of a Large paging area. 


Replacement of private disk pools by appropriate pubsets; this enables 
the advantages offered by the system for processing files on public 
disks to be used here. 


Enhanced availability; if a processor crashes in a multiprocessor syste 
its pubsets can be made available in the remaining processors, the 
entire cataLog and data structure being retained. 


Improved data protection via the option of restricting the shareability 
of a five. 


Reduced restoration times following the destruction of a pubset, thanks 
to the smaller size. 


Several pubsets (max. 36) can exist in one system. Each system contains a 

home pubset, vhich is necessary for Loading, operating and terminating the 
system and must be available throughout the session. ALL other pubsets can 
be imported and exported as required by the system administrator during the 
session, with the exception of pubsets containing files required for paging. 


A 


pubset can consist of several disks. 


The user can create, process and delete files, using all Logical DMS 
functions, on the disks of a pubset. The system recognizes and manages all 
the disks on a pubset as a single unit. 


is the fourth character in the VSN. 


ExampLe: 
PUBAO1 cataLog identifier A 
PUBZO^4 ᾶ catalog identifier Z 


Each pubset contains a JOIN file and its own TSOSCAT. 


Those users who are authorized to access files on a given pubset are 
Specified via their user ID in an entry in the JOIN file: 


If a user is not entered in the JOIN file of a pubset, he cannot access 
this pubset or shareable files of other users, unless the class 2 optio 
FSHARING was set at system generation time. This option allows access 
to a pubset under another user ID. 


If the user has an entry with PUBSPACE=0 in the JOIN file, he can acces 


all shareable files (SHARE=YES) but cannot create any files of his own. 
If PUBSPACE>O is specified, he can also create files of his own. 
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262.65 Space Accounting 

The space management facility provides the job management with data for the 
creation of accounting records. The data evaluated consists of: : 

- number of PAM bLocks reserved 


= duration of reservation. 


Further details can be found in the "System Administrator's Guide" manual. 


2.2.6 Summary 


The previous sections dealt with the concept of volumes in BS2000. The 
Salient characteristics of the various volume types are outlined in Table 
2-2. 4 ; 


Readers should note that pubsets will henceforth be the data volumes used 
in BS2000. The development of private disks will be abandoned. 
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Volume 
characteristics 
Pubset MPVS 


Volumes 


Volume type 


Private volumes 


Storage medium Disk Disk; 

tape 
Number of gobs Any number Disk: 1 (if the disk is 
which may use exclusively reserved; 
the volume otherwise any number). 
simuLtaneousLy Tape: 1 
File The DMS guarantees full file protection (cf. section 2.1.5, 
protection "File Protection") 
Processing DMS access methods of the operating system; I/O macros of 
methods the operating system that process system files; TOS Monitor 

© allowed macros that process TOS system files. 

Labels For disks, standard Labels are 


6-character alphanumeric 
field; the first three 
characters must be PUB; 
the fourth is the catalog 
identifier (catid) of 

the pubset. 


Volume serial 
number 


VoLume is 
mounted 


For the home pubset, at 
the start of the session; 
other pubsets can be 
imported by the system 


administrator as required 
but must be imported 
before the pubset is 
first accessed. 


The home pubset is 
retained throughout the 
session. Other pubsets 
can be removed by the 
system administrator 
when they are no Longer 
required. 


Space Yes 

dynamically 

acquired during 

execution of a 

user program 

es 


required 
Volume characteristics 


VoLume is 
dismounted 


Table 2-2: 
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supported, but not user Labels. 


6-character alphanumeric field; 
the first three characters must 
not be PUB. 


When requested by a job. 


Tape devices: on request, or when 
the job requesting the voLume is 
terminated; 

disk devices: by the operator, 
partly on request from the system 
(new MOUNT message). 


Yes 


Yes, unless the user wants to 
risk his job being aborted if the 
voLume is not available (e.g. 

no suitable device is free). 
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2.3 DEVICES 


2.3.1 Which Devices are Available to User Jobs? 


A user job is able to reserve for itself almost every peripheral device; 
exceptions may be found below. 


Usually a user job can restrict itself to reserving tape and disk devices. 
Other devices such as printer and punch card devices are controlled by the 
system and may be addressed via the interfaces provided by the softvare 
product SPOOL (PRINT and PUNCH commands, WRLST macro, etc.). 


Devices that cannot be reserved for individual jobs are: 


- consoles 

- disk devices for public volumes 

- devices assigned to the system by the operator (e.g. printer and punch 
card devices). 


These devices are system resources. 


2.5.2 Requesting Devices 


User jobs can request and reserve devices and voLumes by means of the 
commands 


FILE and 
SECUREL[ -RESOURCE-ALLOCATIONJ 


The SECUREL-RESOURCE-ALLOCATION] command can also be used to reserve other 
resources, e.g. files on public volumes. 


If neither of these commands is used, the DMS attempts to reserve the 
required devices when opening a file. 


Devices and volumes needed for a certain file are requested using the FILE 
command. 


If a file which extends over more than one private volume is reserved by 
means of a SECUREL-RESOURCE-ALLOCATION] command, the DMS reserves all the 
volumes and the devices they require. 


Furthermore, in batch mode, the SECUREL-RESOURCE-ALLOCATION] command 

causes the job to wait if one of the devices requested is not available at 
the time of the request. However, the maximum wait time can also be 
specified explicitly in the WAIT operand of the SECUREL-RESOURCE-ALLOCATION] 
command for both batch and interactive mode). 
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When requested, devices may be selected by means of the following attributes: 

e According to the device type (applies to FILE and SECURE[-RESOURCE- 
ALLOCATION] commands; in this case, the DMS selects any free device of 
the specified type. 


ExampLe: 


/FILE DATEI,LINK-EIN,DEVICE-D3465,VOLUME-DSKOO1 
/SEC-RES DISK-z(VOL-DSK002,T-2D3480) 


or 
/SECURE VOL=DSK002/D3480 

Using the mnemonic device name (applies only to the SECURE command). If it 
is free, the device vith the designation specified is reserved by the DMS. 
However, this sort of reservation is possible for SPECIAL applications 
only. 

Note: 

The reservation of disk devices according to type by the SECURE[-RESOURCE- 
ALLOCATION] command is possible for SPECIAL appLications only (e.g. 
VOLIN); for example: /SEC D3465=2). 


ExampLe: 


/SECURE UNIT-A1 


2.3.3 Reserving Devices Using the Data Management System 


The DMS processes device requests as follows: 


If the requested devices are free: 


The DMS reserves the devices for the requesting job. If voLumes are 
requested at the same time, the DMS sends a mount request to the operator 
(MOUNT message displayed on the console). For files on private disks, all 
disks containing parts of the relevant file must be mounted. 


If at Least one of the devices requested is not free: 


In interactive mode an appropriate message is sent to the terminal. No 
devices are reserved. This applies regardless of whether a FILE command or a 
SECUREL-RESOURCE-ALLOCATION] command vas used to request them. 


If a SECUREL-RESOURCE-ALLOCATION] command vas used for the request, the job 
is placed in the SECURE queue in accordance with the values in the WAIT 
operand and with its type (batch, dialog). Processing of the job continues 
when all the requested devices are free. If a FILE command vas used or if 
not all the requested devices are free after the maximum wait time in a 
SECUREL-RESOURCE-ALLOCATION] command, all subsequent commands until the next 
STEP or LOGOFF command are skipped. 
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2.2.4 Releasing Devices 


Devices assigned to a file may be deallocated by means of the RELEASE 
command. 


2.3.5 Methods of Requesting Devices for Jobs in which CLass 1 
Programs are Executed 
These jobs can also use the FILE and SECUREL-RESOURCE-ALLOCATIONJ] commands 
to request devices. 
In addition, they have the following options: 


e Using the TOS FILE command to request assignment before program 
execution. 


e Using the ASSGN macro to request assignment during program execution (see 
Appendix A.5). 


e If the program empLoys the physical Level of the FCP and does not use 
either of the above options to request devices, the required devices, 
if free, are assigned by the DMS vhen processing the first EXCP or EXCPW 
macro. 


The DDEV (TOS) or CLOSE (TOS) macro can be used to release devices from a 
cLass 1 program. 


2.3.6 Qperator Intervention 

If a job has successfully requested devices and volumes, intervention by 
the operator is necessary to mount volumes on the appropriate devices. 

The DMS controls this activity by means of messages that request the 
Operator to mount a volume on a particular device (MOUNT messages). Each of 
these messages contains the volume serial number (VSN) of the volume 
concerned and the mnemonic device name of the device already reserved by 
the DMS for the requesting 3605» 

The operator can react as follows: 


® by mounting the volume on the designated device; 


èe by mounting the volume on another device of the same type as specified 
in the message. 


Any other operator reaction is rejected by the DMS, e.g. he does not mount 
the voLume and thus causes an error message to be sent to the user. 
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2.53.7 Management of Private Disks 


The user sees onLy the reservation of the voLume, the required device being 
managed by the system. The device is not reserved. 


ALL reservation functions executed as a result of DMS calls are interpreted 
as requests for shareabLe reservation. 


The SECUREL-RESOURCE-ALLOCATIONl1 command offers the possibility of reserving 
a private volume either exclusively or as shareabLe. 


The control and monitoring of volumes can be set and modified by means of 
operator commands (cf. section 2.3.8). 


ExampLes: 


- mounting, dismounting, remounting of voLumes 
e - setting of availability specifications independent of the online status 
- control of excLusive/shareabLe operation of volumes (including SPDs) 
- defining the time at which a device is to be reserved/released by a 
voLume | 
=- permanent or temporary removal of volumes 
- consistency of disk Locks 


Device management offers online monitoring of the volumes in use. 


2.3.8 Volume Monitoring 


VoLume monitoring supports and monitors disk utilization, i.e. 


- the mounting of disks prior to use 

- the remounting of devices during use 

=- the protection of disks against errored device access (data security and 
data protection). 


© To ensure the availability of the system function "volume monitoring", it 


has a permanent task for disk monitoring. Operations that temporarily affect 
availability are executed by temporary tasks. 
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3 COMMANDS 


This chapter contains descriptions of the commands for data and device 
management. 

ALL commands and operands can be truncated (right to Left) as Long as they 
remain unambiguous. 


3-1 DATA MANAGEMENT 


© CATALOG PROCESS CATALOG ENTRY 


The CATALOG command is used to create or update the catalog entry for a file 
or for a file generation group (FGG); in particular, it allows the user to 
specify file protection measures. 

The user can convert a temporary file into a permanent one or vice versa. 


Format 1 for the catalog entry of single files 


Operation Operands 


Ed pathnameil[ ,filename2] 
CAT NLEWJ WR | NO 
C,STATE= JL,ACCESS- lL,SHARE- amr 
ULPDATEJ READ YES 
NONE NONE 
© L ,WRPASS- J0,RDPASS= 1 
passvord1 passvord2 
A 
ο Β 
C,EXPASS= lL,RETPDzdayslL,BACKUP-1Cf(1 
passvord3 D 
E. 
SUCC 
YES YES FAIL 
L ,LARGE- JL,DESTROY- lL,AUDIT- J 
NO NO ALL 
NONE 
'" "pathname1" stands for: [:catid:l[suserid.J]fiviename1 
catid This operand denotes the catalog identifier. If no entry is 


made, the default value assigned to the user ID is assumed. 


UB05-J-Z55-5-7600 er! 


CATALOG 


userid 


filenamel 


filename2 


STATE=NLEW] 


=UCPDATE] 


ACCESS=WRITE 


=READ 


SHARE=NO 


=YES 


WRPASS=NONE 


=password1 


This operand denotes the user identification. If this 
operand is omitted, the user's own user ID is assumed. Only 
the user's own user ID is allowed. 


This operand specifies the fully: qualified name of the file 
or temporary file to which the subsequent operands refer. 
The name of a file generation is allowed only for the 
purpose of creating its catalog entry (see the operand 
STATE=NEW). 


This operand specifies the new fully qualified name of a 
file or temporary file to which "filename1" is to be 
changed. "catid" and “userid” must not be specified. The 
command is rejected if STATE=UPDATE is not specified. 


This operand specifies that a new catalog entry is to be 
created, i.e. the other operands in the CATALOG command 
describe a file which does not yet exist. 


This operand specifies that an existing catalog entry is to 
be modified. A field in the catalog entry can be modified 
only if the appropriate operand is specified explicitly, 
since omitted operands are not replaced by their default 
values. 


If the file is passvord-protected, the password required 
for write access must be specified in order to update the 
catalog entry. The question of which passwords are to be > 
specified for a specific access is discussed in 

section 2.1.5 (Table 2.1). 


This operand specifies that both read and write access are 
allowed for this file. 


This operand specifies that only read access is permitted. 
This entry must be specified in conjunction with the 
operand STATE-UPDATE, i.e. it affects only catalog entries 
which already exist. 


This operand restricts access to the file or its catalog 
entry to the owner only, i.e. the file is non-shareabLle. 


This operand specifies that the file or its catalog entry 
may be processed under any user ID, i.e. the file is 
shareable. 


No write password is required to write to the file. 


This operand defines the password required for writing to 
the file. Up to 4 bytes can be specified for the file 
protection passwords in the operands RDPASS, WRPASS and 
EXPASS: 


C'x" "X" represents 1 to 4 alphanumeric characters 
and special characters; 

ΧΩ" "nh" represents 1 to 8 hexadecimal digits; 

d "d" represents 1 to 8 decimal digits whose value 


is converted to a binary value. 
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RDPASS-NONE 


-passvord2 


EXPASS=NONE 


=passvord3 


RETPD=days 


BACKUP= 


CATALOG 


When a CATALOG command is output to the system file SYSLST 
(job Logging) or SYSOUT (in the case of procedures), all 
passvords are overwritten with the Letter "S". 


Protection of a file by passwords is enhanced if the 
System uses password encryption. This means, for example, 
that only encrypted passwords are contained in memory 
dumps; misuse is thus made impossible. 


At system generation, password encryption can be preset 
(system parameter ENCRYPT). 


No read password is necessary to read the file. 


This operand defines the password required in order to read 
the file. 


No password is necessary to execute the file (Load module, 
DO or ENTER procedure). 


This operand defines the password required for execution 
of a file. 


This operand specifies the file retention period in days, 
during which time the file can be read only. 

"days" must be a decimal integer, the maximum value of 
which is calculated from the difference in days between 
the end of the century (31.12.99) and the current date. 
If STATE=NEW is specified, this operand is ignored. 

If STATE-U is specified, this retention period can be 
specified for existing files only, i.e. the creation date 
must be greater than O (CRDATE field in the output of the 
FSTATUS command). Once the retention period has expired, 
the file can be modified, but it is not automatically 
deleted. 

Default value: zero days, i.e. the file can be modified 
immediately. ; 


This operand specifies the frequency with which the file is 
to be saved (creation of backup)». This information is 
needed for the regular save runs performed by the file 
saving system ARCHIVE. 


Most frequent saving. Files defined thus are saved in 
every save run. 


Files defined thus are saved if a save run for files 
with BACKUP=B or C or D takes place. 


Files defined thus are saved if a save run for files 
with BACKUP=C or D takes pLace. 


Least frequent saving. Files defined thus are saved only 
if a save run for files with BACKUP=D takes pLace. 


No saving by ARCHIVE, wecebt in the case of DEXPORT. (This 
is relevant for work files, for example. ) 


Default value: 
The default value for BACKUP is determined by the system 
administrator at system generation time. 
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LARGE=YES 


ΞΝΟ 


DESTROY=YES 


AUDIT= 


=SUCC 


=FAIL 


=ALL 


=NONE 


In save runs using ARCHIVE, only those PAM blocks are saved 
which have been changed since the Last full save operation. 
This is of particular relevance for Large files. 


The file is saved in its entirety in every save run using 
ARCHIVE. 


Whenever a file is deleted, its storage space is 
overwritten with binary zeros. 


When the file is deleted, its storage space is returned 
unchanged to the system unless data destruction was 
explicitly requested (DESTROY operand in the ERASE 
command). 


This operand monitors file access operations by means 

of system exit routines for the specified file. 

CATALOG, ERASE, FILE and OPEN operations may be 

monitored. 

This monitoring of file access operations can be restricted 
to specific user IDs by means of the operand AUDIT in the 
JOIN command (see the "System Exits" manual. 


ALL successful DMS actions for the file are to be 
monitored. 


ALL unsuccessful DMS actions for the file are to be 
monitored. 


ALL DMS actions for the file are to be monitored. 


No monitoring. 


Notes on temporary fiLes: 


- The RETPD operand has no effect. 


- The following system default values apply and cannot be modified: 


RETPD=0, RDPASS=NONE, WRPASS=NONE, SHARE=NO, ACCESS=WRITE, BACKUP=E 


- When recataloging a temporary file as a permanent file: the file 
attributes are taken over. 
When recataloging a permanent file as a temporary file: the default 
values are used for the attributes. 
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Format 2 for the cataLog entry of fiLe generation groups 


Operation Operands 


oue pathname1l ,filename2] 
CAT 


CEW 
c STATE=| UCPOATE] h 
FLOREIGNJ 


WRITE 
L,ACCESS- J 
READ 


NO 
¢/SHARE=| h 
YES 


c MRPASS=| h 
password1 


L/RDPASS-| h 
password2 


L,RETPD-dayslL,GEN-max]l 


CYCLE 
REUSE 


C,DISP= ] 
DELETE 
KEEP 


absbas ? 
[,BASE- 1 
reULbas 


L,FIRST-nl1L,DEVICE-devicelL,VOLUME-vsnl 


A 
B 

L ,BACKUP-1Cr[J 
D 
E 


YES 
[,LARGE- J 
NO 


YES 
C,DESTROY= J 


NO 


SUCC 
FAIL 
L,AUDIT- ] 
ALL 
NONE 
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"pathnamel" stands for: [:catid:l[$userid.lfivename1 


catid 


userid 


filenamel 


filename2 


STATE-NLEWJ 


-ULPDATEJ 


=FCOREIGN] 


This operand denotes the catalog identifier. If no entry is 
made, the default catalog ID assigned to the user ID is 
assumed. | 


This operand denotes the user identification. If this 
operand is omitted, the user's own user ID is assumed. Only 
the user's own user ID is allowed. 


This operand specifies the name of a file generation group 
to which the subsequent operands refer. 


This operand specifies a new name for file generation group 
"filLename1". The user ID and/or the catalog identifier 
must not be specified. 


The command is rejected if STATE=UPDATE is not specified. 


This operand specifies that a new catalog entry is to be 
created, i.e. the other operands in the CATALOG command 
describe a file generation group which does not yet exist. 


This operand specifies that an existing catalog entry is 
to be updated. If no entry is made, the default value is 
not assumed. Thus, a field in the catalog can be modified 
only if the appropriate operand is specified explicitly. 


If the file is password-protected, the password required 
for write access must be specified in order to update the 


.cataLog entry. The question of which passwords are to be 


specified for a particular access is described in section 
Qe 4125 (TabLe 271). 4 


This operand must be specified for a file generation group 
if the Latter is on private disks and does not yet have a 
catalog entry (FOREIGN file generation group). In addition 
to this operand, the DEVICE and VOLUME operands must be 
specified in the CATALOG command. 


In addition, a FILE command with the entries 
"STATE=FOREIGN,DEVICE=...,VOLUME=...™" must be given 
for each individual generation within a FOREIGN file 
generation group. 


The following table illustrates the permissible combin- 


ations of STATE=NEW, UPDATE or FOREIGN with the other 
operands in the CATALOG command: 
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ACCESS=WRITE 


=READ 


SHARE=NO 
=YES 


WRPASS-NONE 
=password1 
RDPASS=NONE 


=passvord2 


RETPD=days 


CATALOG 


FOREIGN 


| NEW | STATE-UPDATE 


Operands 


ACCESS 
SHARE 
passwords 
RETPD 


absbas 
BASE= 


reLbas 


DEVICE 
VOLUME 


This operand specifies that both read and write access are 
allowed for this file generation group. 


This operand specifies that only read access is permitted. 


This entry must be specified in conjunction vith the 
operand STATE-UPDATE, i.e. it can be specified only where 
the catalog entry already exists. 


This operand restricts access to the file generation group 
or its catalog entry to the owner, i.e. the file is 
non~-shareabLe. 


This operand specifies that the file generation group or 
its catalog entry may be processed under any user ID, i.e. 
the file is shareable. 


No write password is required to write to the generations 
of the file generation group. 


This operand defines the password required for writing 
(see format 1) 


No read password is necessary to read the generations of 
the file generation group. 


This operand defines the password required for reading. 


This operand specifies the file retention period in days, 
during which time the file can be read only. 

"days" must be a decimal integer, the maximum value of 
which is calculated from the difference in days between 
the end of the century (31.12.99) and the current date. 
If STATE=NEW is specified, this operand is ignored. 

If STATE=U is specified, this operand is effective for 
generations whose creation date is greater than 0, but is 
ignored for all other generations. 

Once the retention period has expired, the file can be 
updated, but it is not automatically deleted. 

Default value: zero days, i.e. the file can be updated 
immediately. | 
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GEN=max 

DISP= 
=CYCLE 
=REUSE 
=DELETE 
=KEEP 

BASE= 
=absbas 


This operand specifies the maximum number of generations 
which can be cataloged simultaneously for the file 
generation group "filename1". The maximum value is 

255 and should not be equal to D. 


If STATE=NEW and GEN=0 are specified, a file is created 
instead of a file generation group. 

The GEN operand can be specified either for a new file 
generation group (STATE=NEW) or in conjunction with 
STATE=UPDATE. 


This operand specifies what is to happen when the number of 
cataloged file generations reaches the maximum value 
defined in GEN and a further file generation is to be 
cataloged. 


This operand specifies that the oldest generation (see the 
FIRST operand) and its catalog entry are to be deleted. 


The same as for CYCLE, provided that the generations of the 
file generation group are Located on public volumes. 

If the generations of the file generation group are Located 
on private disks, the oldest generation is deleted and 

the new one is created on the same volume. If the deleted 
generation extended over a number of disks, only the first 
disk is used to catalog the new generation. 


This operand specifies that all existing file generations 
are to be deleted. A new series of generations is thus 
started as soon as the maximum value specified in GEN has 
been exceeded. 


This entry suppresses the automatic deletion of generations 
older than that most recently processed, even if the 
maximum number of generations is exceeded in doing so. The 
FIRST and BASE values can be modified only by means of the 
CATALOG command with STATE=U. This command also effects 

the deletion of the surplus older generations. 


This operand specifies the base value for file generation 
group "filename1", to which all relative generation numbers 
within a job refer. 


If the BASE operand is omitted, it receives the following 
value by default: 


- value of the FIRST operand if no generation is present; 
- zero, if no generation is present and no FIRST operand 
was specified. 


This operand specifies a decimal number (1 to 4 digits) 
greater than 0, which is to become the new base value for 
the file generation group. 


If "absbas" is specified in conjunction with STATE=UPDATE, 
the new base value, which must define an existing file 
generation, is inserted in the catalog entry of the file 
generation group. 
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If BASE-absbas is specified in conjunction with STATE=NEW, 
absbas is inserted as the base value in the catalog entry 
and as the Latest generation number (LASTGN field in the 
FSTAT output). A CAT command with the BASE operand must be 
specified if several file generations are to be imported, 
which are contained on private disk and whose group entry 
no Longer exists (in the Catalog and in the F1 Label). For 
an exampLe see the IMPORT command. 


ΞΓθἰ. 085 This operand specifies a new base value for the file 
generation group. "reLbas" must be < O and must not exceed 
two digits. BASE is derived as follows: 

BASE = (Latest generation number + "relbas") 


BASE-reLbas can be specified only in conjunction with 
STATE-UPDATE. The new base value must define an existing 
file generation, i.e. positive numbers must not be used. 


e FIRST=n This operand specifies the number of the oldest existing 
file generation, where "n" is a decimal number of 1 to 4 

digits. The value of "n" must be Less than that in the 
operand BASE, and the difference between these vaLues 
must not exceed the number specified by GEN. 
The operand FIRST can be specified only for file 
generation groups to be cataLoged for the first time, 
i.e. in conjunction with STATE=NEW. 


Note: 

The operand FIRST is required in order to restore the 
catalog entry of a FOREIGN file generation group on private 
volumes. It should be used for this purpose only. 


DEVICE=device This operand specifies a disk device. For a formal 
description, see the DEVICE operand in the FILE command. 


VOLUME=vsn This operand specifies the volume serial number of the 
private disk on which the catalog entry of the file 
generation group is Located, or is to be Located. 


The operands VOLUME and DEVICE must be specified in 
© conjunction: 


- with STATE=NEW in order to create a file generation 
group on private disks; 

- with STATE-FOREIGN to restore a file generation group 
which already exists on private disks. (In this case, 
the BASE, FIRST, GEN and DISP entries are transferred 
from the F1 Label to the catalog.) 


If the file generation group is cataloged on a private 
disk, all associated generations must also be Located 
on private disks, and be generated by an appropriate 
FILE command or FILE macro. 
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BACKUP= 


LARGE=YES 


=NO 


DESTROY=YES 


-NO 


AUDIT- 


3-410 


This operand specifies the frequency with which the five is 
to be saved (creation of backup). This information is 
needed for the regular save runs performed by the file 
saving system ARCHIVE. 


Most frequent saving; files thus defined are saved in 
every save run. 


Files defined thus are saved if a save run for files 
with BACKUP=B or C or D takes place. 


Files defined thus are saved if a save run for files 
with BACKUP=C or D takes place. 


Least frequent saving; files defined thus are saved only 
if a save run for files with BACKUP=D takes place. 


No saving by ARCHIVE. (This is of relevance for work files, 
for exampLe. ) 


Default value: 
The default value for BACKUP is defined by the system 
administrator at system generation time. 


In save runs using ARCHIVE, only those PAM blocks which 
have been modified since the Last save operation are saved. 
This is of particular relevance for Large files. 


The file is saved in its entirety in every save run 
using ARCHIVE. 


Whenever the file is deleted, its storage space is 
overwritten with binary zeros. 


When the file is deleted, its storage space is returned 
unchanged to the system unless data destruction was 
specifically requested (DESTROY operand in the-ERASE 
command). 


Note for the BACKUP, LARGE and DESTROY operands: 

The values of these operands apply to the file generation 
group as a whole. It is not possible to specify these 
attributes separately for individual generations. 


This operand monitors the file access operations by means 
of system exit routines for the named file. — 

CATALOG, ERASE, FILE and OPEN operations can be monitored. 
This monitoring of file access operations can be restricted 
to specific user IDs by the AUDIT operand in the JOIN 
command (see the "System Exits" manual). 


ALL successful DMS actions for the file are to be 
monitored. 


ALL unsuccessful DMS actions for the file are to be 
monitored. 


ALL DMS actions for the file are to be monitored. 


No monitoring. 
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Notes: 


- Only the attributes of the group can be modified for file generations of 
a file generation group. Equally, the group attributes must already be 
defined before file generations are added to this group (see the FOREIGN 
entry in the FILE command). 


- When the output generated by a CATALOG command is directed to the system 
file SYSLST (job Logging) or SYSOUT (in the case of procedures), all 
passwords are overwritten with the Letter "S". 


- A file can be recataloged as a file generation; it need not be copied. 
This applies only if the file generation does not yet exist. 
However, a file generation cannot be recataloged as a file. 


Network catalog management (see also the "MSCF Multiprocessor System" 


manual) 


e The user of the multiprocessor system can specify a unique "path name", 
which also contains a catalog identifier, as a supplement to the currently 
existing file name. 


The catalog identifier and the user ID must not be modified when changing 
this name, i.e. it is not possible to specify a catalog identifier and/or a 
user ID in "fivlename2". 
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Example 1: Format 1 


/FSTAT CAT. TEST 

% DMSOS33 REQUESTED FILE NOT CATALOGED ON PVS V. CMD TERMINATED 

ICAT CAT. TEST | ———————————————————————————————— M 
/FSTAT CAT. TEST,ALL 

0000000 :V: $P1211034. CAT. TEST 


FCBTYPE - NONE VSNTYPE - PUB 
SHARE = NO ACCESS = WRITE 
ACCESS# = 000 CRDATE = NONE EXDATE = NONE LADATE = NONE 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = OOO BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE 
BLKTYPE = NONE BLKSIZE = 000000 RECFORM = NONE RECSIZE = 00000 
VSN/DEV/EXT = NONE 

:V: PUBLIC: 1 FILE. RES= 0, FREE= 0, REL= O PAGES 


1) The CATALOG command catalogs the file CAT. TEST and enters the default 
values, as shown in the subsequent FTATUS command. 


Example 2: Format 1 of the CATALOG command 


The three files PROG1, PROG2 and PROG3 contain executable programs: 


/CAT PROG1L,RDPASS=NONE ,EXPASS=NONE ,STATE=UPDATE 1) 
/CAT PROG2,RDPASS=X'FF11" ,EXPASS=NONE,STATE=U 2) 
/CAT PROG3,RDPASS=C'LIES’ ,EXPASS=X'123456*" ,STATE=U 3) 


1) File PROG1 can be read and executed. 


2) File PROG2 cannot be read without knowledge of the read password 
X'FF11', but the Load module in file PROG2 can be Loaded with the EXEC 
or LOAD command and then started. 


3) The system permits processing of file PROG3 only if it has knowledge 
of at Least one of the passwords C'LIES' and X'1234565'. If a user knows 
only password X'123456', he can execute the program on the file but he 
cannot read the file. If a user knows the read password C'LIES', this 
suffices to allow him to read and execute the file. 
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ExampLe 3: Format 1 of the CATALOG command 
The file DO.BEISPIEL contains a DO procedure. 


/DO DO. BEISPIEL | ————— — ——— — — ———————————————————————— 1) 

* BLSO517 MODULE TEST LOADED. 

PROZEDUR LAEUFT | ————————————————————————————— 2) 

/CAT DO. BEISPIEL,EXPASS-zC'NOEX' , STATE-U 3) 

/DO DO. BEISPIEL 

X EXCO141 PROCEDURE FILE DO.BEISPIEL CAN'T BE OPENED. DMS ERROR CODE 0091 
CMD TERM 

/PASSWORD C*NOEX' | —————————————————————————————— 4) 

/DO DO. BEISPIEL 

*  BLS0517 MODULE TEST LOADED. 

PROZEDUR LAEUFT 


1) Since the file DO.BEISPIEL is not protected by an execute passvord, 
it may be executed vithout specification of a password. 


e 2) Procedure executing. 


3) The file is given an execute password. From now on it cannot be 
executed unless this password is specified. 


4) After the password has been entered, the file can be executed again. 


ExampLe 4: Format 2 of the CATALOG command 
A file generation group (FGG or DGG) vas defined as follows: 
/CAT GROUP,FIRST-1,GEN-3,BASE-3,DISP-KEEP 


The command sequence below then works out as follows: 


Command: BASE: FIRST: LAST: AbsoLute number 
/LOGON ... 3 ν ἢ 3 ο 
/FILE GROUP( +1) 3 Δ. 4 4 
6 /FILE GROUP(-1) 3 ν ἃ 4 2 
/FILE GROUP( +2) 3 1 5 5 
JEXEC ... 
/CAT GROUP,STATE=U, 
BASE=0 5 3 5 5 


The older generations, 1 and 2, are deleted by the CATALOG command; the 
new BASE value is 5; the new FIRST value is derived from the following: 


BASE(S) - GEN(3) + 1 = FIRST(3) ; 
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Example 5: Format 2 


/CAT DGG1,GEN=5 | ———————————————————————— 1) 
/FSTAT DGG1,ALL 
0000000 :V:$PN211034.DGG1 (FGG) 


SHARE = NO ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-19 EXDATE = 85-03-19 LADATE = NONE 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = OOO BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE 
GEN = 00005 BASE = 00000 LASTGN = 00000 FIRSTGN = 00000 
DISP = CYCLE 

:V: | PUBLIC: 1 FILE. RES= O, FREE= 0, REL= O PAGES 


/CAT DGGL( *1) 

ICAT AIOE i editing liana neater S 

X DMSO6C7 USER ATTEMPTED TO PROCESS A GENERATION WITH AN INCORRECT GENERATION 
NUMBER. COMMAND TERMINATED 

/CAT DGG1(x*2) | 

/CAT DGG1(x*3) 9 
/CAT DGG1(*4) 

/CAT DGG1(x*5) 

/FSTAT DGG1,ALL 

0000000 :V:SPM211034.DGG1 (FGG) 


SHARE = NO ACCESS = WRITE | 
ACCESS# = 000 CRDATE = 85-03-19 EXDATE = 85-03-19 LADATE = NONE 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 BACKUPAÁ = 000 .. LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE 
GEN = 00005 BASE = 90000 LASTGN = 00005 FIRSTGN = 00001 
DISP = CYCLE 
sV: PUBLIC: 4 FILE. RES Ο, FREE= 0, REL= O0 PAGES 
/CAT DGG1(*6) mues 55) 
/FSTAT DGG1,GEN=YES 
0000000 :V:$PM211034.DGG1 (FGG) 
0000000 :V:$PM211034. DGG1( *0002) 
0000000 :V:$PM211034. DGG1 ( *0003) 
0000000 :V:$PM211034. DGG1 ( *0004) 
0000000 :V:$PM211034. DGG1 ( *0005) 
0000000 :V: $PM211034. DGG1( *0006) 
:V: PUBLIC: 6 FILES. RES- 0, FREE= ο, REL= O PAGES 
/FSTAT DGG1,ALL 9 
0000000 :V:$PM211034.0GG1 (FGG) 
SHARE = NO ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-19 EXDATE = 85-03-19 LADATE = NONE 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE | 
GEN = 00005 BASE - 00000 LASTGN = 00006 FIRSTGN = 00002 
DISP - CYCLE 
:V: PUBLIC: 1 FILE. RES= 0, FREE= ο, REL= O PAGES 


1) A maximum of 5 file generations are to be cataloged for the file 
generation group DGG1. 


2) The file generations must be cataloged in unbroken ascending order. 


3) If the number of file generations exceeds the value Laid down in the GEN 
operand, the oldest generation is deleted in each case (here (*1)). 


For further exampLes see the PASSWORD command. 
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CHANGE CHANGE TFT ENTRY 


The CHANGE command changes the file Link name in a Task File Table (TFT) 
entry. ALL other values in the entry remain unaltered. 


Operation Operands 
CHANGE ClLink1] ,Link2 
Link1 This operand specifies the file Link name (1 to 8 bytes). 


If this operand is omitted, the first TFT entry with the Link 
name C'.....ooe" is processed. 


Link2 This operand specifies a new file Link name which is to 
replace the previous file Link name. 


Note: 


The CHANGE command is meaningful only for a TFT entry which was previously 
created by means of a FILE command/macro (and not with OPEN). 

The reason for this is the differing treatment of the TFT entry upon 
reopening the file (see section 5.1, "Opening Files"). 


ExampLe:. 


The moduLe UNSORT generates an output file, which is subsequently to be 
sorted ("SORTIERT") by means of the SORT utility routine. 


/FILE DATEN. UNSORTIERT,LINKsUNSORT,SPACEs12  ————————— — — ————————— 1) 
/EXEC (UNSORT ,RNO. MODLIB) i 

* BLSOOO1 DLL VER 822 

/CHANGE UNSORT,SORTIN | ———————— — —————— ———————————————— 2) 


./FILE DATEN. SORTIERT,LINK-SORTOUT 


/EXEC $SORT 

* BLSOSOO PROGRAM SORT, VERSION 710 OF 84-12-17 LOADED. 
* SRT1001 12:55:04/000000. 00 SORT/MERGE STARTED, VERSION 71A00 
% SRT1130 PLEASE ENTER SORT STATEMENTS 

*sort fields=(1,4,a,ch) 

*end - 

* SRT1116 NUMBER OF OUTPUT RECORDS - 00000005000 

% SRT1116 NUMBER OF INPUT RECORDS - 00000005000 

% SRT1116 NUMBER OF SORTED RECORDS - 00000005000 

% SRT11046 CPU TIME USED: 0002.7 

/REL SORTOUT 


1) This FILE command Links the file DATEN. UNSORTIERT (=data. unsorted) with 
the moduLe UNSORT; this moduLe uses the Link name UNSORT. 


2) The CHANGE command assigns the file DATEN. UNSORTIERT to the software 
product SORT as an input file, i.e. the file Link name UNSORT is 
repLaced by SORTIN. 


For a further example see the HOLD command. 
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COPE COPY FILE 


The COPY command copies files, file generations or file generation groups, 
without altering them, from: 


- disk to disk 
- disk to tape 
- tape to disk. 


In order for the COPY command to be able to process them, tape files must 
have the standard block format (multiples of 2048 bytes). 


Operation Operands 

COPY REPLLACEJT 
ΥΓΕΞ5] 

pathname1,pathname2[,SAME] L,WRITE-Z|NEWL,DIALLOGl- 1|1 

NCO] 

*pathname1” stands for: [:catid:][$userid.]fiLename1 

"pathname2" stands for: [:catid:][$userid.]fiLename2 

catid This operand denotes the catalog identifier associated with 


the file. If no entry is made, the default catalog ID 
assigned to the user ID is assumed. 


userid This operand denotes the user identification associated 
with the file. If this operand is not specified, the user's 
own user ID is assumed. 


filenamel This operand specifies the fully qualified name of a file, 
file generation or file generation group which is to be 
copied. 


If the file does not belong to the user's own user ID, it 
must be shareable (SHARE=YES) and the user ID must be 
specified. 


filename2 This operand specifies the name which the copy (file, file 
generation or file generation group) is to bear. 


If "fivlename2" has not yet been cataloged, the file name 
must not start with a foreign user ID, and is to be entered 
without it (cf. example 2). If the file does not belong to 
the user's own user ID, it must be declared shareable 
(operand SHARE=YES in the CAT command) and the user ID 

must be specified. 


If "fivename2" is the name of a file generation group, this 
must also be true for "filename2", i.e. a file or file 
generation cannot be copied to a file generation group. 
Note: 


"pathnamel1" must not be identical with "pathname2". 
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SAME This operand specifies that "fivlename2" is to receive the 
same file protection attributes as "fivlename1" (same 
passwords, same retention period, same shareability, same 
access authorization). 

If the SAME entry is omitted, a file ("filename2") to be 
cataloged is created as a non-shareabLe file (5ΗΑΒΕΞΝΟ) 
and is free for both read and write access. 

SAME is ignored if the output file is a file generation, 
Since its file protection is determined by the associated 
file generation group. It is also ignored if the output 
file is cataloged under another user's user ID. 


Note: 

The value for AUDIT from the catalog entry, which organizes 
the file accesses via exit routines, is not transferred to 
the copy with SAME. 


WRITE= If the file, file generation or file generation group 
e defined by "pathname2" already exists and is not empty, 
the user can determine whether or not this file is 
overwritten. 


-REPLLACE] The file, file generation or file generation group defined 
by "pathname2" is overwritten without a message (default 
value). 


=NEW The file is not copied; the command is rejected. In the 
| case of procedures, the message "pathname2 ALREADY EXISTS. 
COMMAND TERMINATED" is displayed and a branch is made to 
the next STEP command. 


DIALLOGJ- This operand determines whether or not the query 
"OVERWRITE (Y/ND)?" is displayed, and is interpreted only 
in interactive mode and if WRITE=NEW is specified. 


-YLES] Tne user is asked if the file is to be overwritten. 


ΞΝΓΟΙ The existing file is not overwritten. The message 
"pathname2 ALREADY EXISTS. COMMAND TERMINATED” is displayed. 


e Notes: 


= The COPY command copies files in blocks (1 PAM block = 2048 bytes) and 
cannot therefore be used to modify file attributes during copying. It 
cannot, for instance, convert a SAM file into an ISAM file, or fixed- 
Length records into variable-Length records. 


- The COPY command is rejected if output file "filename2" is free for read 
access only (ACCESS=READ in the CATALOG command), or if the secondary 
allocation of the output file is O and the primary allocation is 
inadequate. 


If the file "filLename2" has not yet been cataloged, this is effected 
during processing of the COPY command. This output file is subsequently 
created on public disks under the user's own user ID. 


If output file "fivlename2" is to be placed on private disk and has not 


yet been cataloged, the user must issue an appropriate FILE command for 
the output file prior to the COPY command. 
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If the file to which the copy is to be made has not yet been cataloged, 
the secondary allocation is taken over from the original disk file. If 
the original file is on tape, default values are assumed for primary 
and secondary allocation. 


Only a file generation group which consists of SAM file generations with 
the same file characteristics (same record and bLock Length and the same 
record format) can be copied to a single file or file generation. In this 
case, the file generation must not belong to the file generation or T 
which is to be copied. 


A file generation group can be copied into another file generation group 
only if one of the following conditions is fulfilled: 


a) The group entries for both file generation groups match (i.e. the 
vaLues of GEN, FIRST, LASTGN and BASE are the same). 
The file generation group into which the DMS enters the copy must 
already contain all the generations from FIRST to LASTGN (i.e. the 
generations must be cataloged and be provided with storage space). 


b) The value of GEN is the same for both file generation groups, and the 
file generation group into which the DMS writes the copy does not at 
this stage contain any other generations (i. e. FIRST, LASTGN, and 
BASE have the value zero). 


If a file is to be copied from a foreign user ID "userid", the user ID 
"Suserid" must precede "filvlename1". The file must be shareable 
(SHARE=YES in the catalog entry). 


If a file on private disk has an entry in the system catalog but not in 
the Fl Label, this catalog entry is deleted. If the file is the input 
file, the command is rejected. If it is an output file, a new file is 
created in public space. 


If the file/generation defined by "pathname2" is a tape file, the WRITE 
operand is ignored, i.e. the file/generation is copied whatever happens. 


Remote file access (see also the "RFA" manuaL) 


If a file is to be copied from one remote system to another, with 
input/output being on 2 different systems, this is supported by the 
higher-ranking execution routine. The Local system serves as an 
intermediate station for the data transfer. 


Copying is possible only if the RFASTART command is issued for both 
remote systems before the copying process commences. 


Copying of a Local file generation group from a remote system is not 
possible (error message D5SFF). 


When copying a remote file to a Local file with the SAME operand, the 
passwords are not taken over. 
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ExampLe 1: 


The file DATEI is copied to the file DATEI. KOPIE. 


/FSTAT DATEI,C 
0000006 :V: $PM211034. DATEI 


SHARE = YES ACCESS = WRITE 
ACCESS# = 001 CRDATE = 85-03-19 EXDATE = 85-03-19 LADATE = 85-03-19 
RDPASS = YES WRPASS = YES EXPASS = YES 
VERSION = 001 BACKUP# = 000 LARGE = NO BACKUP = A 
DESTROY = NO AUDIT = NONE 

iV: σος τς: 1 FILE.  RES- 6, FREE= 2, REL= QO PAGES 


/PASSWORD C'DAT"' 

/COPY DATEI,DATEI.KOPIE ——————————————————————————————————— 1) 
/FSTAT DATEI.KOPIE,C 

0000006 :Y: $P1211034. DATEI. KOPIE 


SHARE = NO ACCESS = WRITE 
ACCESS# = 001 CRDATE = 85-03-19 EXDATE = 85-03-19 LADATE = 85-03-19 
e RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 001 BACKUP# = 000 LARGE = NO BACKUP = A 
DESTROY = NO AUDIT = NONE 
:V: PUBLIC: 1 FILE.  RES- 6, FREE- 2, REL- O PAGES 


COPT BATEL;DATEI,WXOPIE,SAME ee 29 
/|FSTAT DATEI.KOPIE,C 
0000006 :V: $P1211034. DATEI». KOPIE 


SHARE - YES ACCESS = WRITE 
ACCESS# = 002 CRDATE = 85-03-19 EXDATE = 85-03-19 LADATE = 85-03-19 
RDPASS = YES WRPASS = YES EXPASS = YES 
VERSION = 001 BACKUP# = OOO LARGE = NO BACKUP = A 
DESTROY = NO AUDIT = NONE 

sY: PUBLIC 


5 1 FILE. RES= 6, FREE- 2, REL- O PAGES 


1) The COPY command generates the file DATEI.KOPIE as a copy of the file 
DATEI. The protection attributes of the file are, however, not adopted. 


2) As a result of the SAME entry, the file DATEI.KOPIE receives the same 
protection attributes as DATEI: SHARE, WRPASS, RDPASS, EXPASS. 
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izxampLe 2: 
Copying to/from a different user ID 


/FSTAT SPM211023. 

0000003 :V: $PM211023. ASS. BEISPIEL2 

0000846 :V: $SPM211023. DYS. BAND 

9000015 :V: $PM211023. DVS. BEISP. 3 

Q000006 :V: $PM211023. DVS. BEISP. 5 

0000006 :V: $PM211023. M. NEU 

2 Vs το ο 5 FILES. RES= 876, FREE= 6, REL= 3 PAGES 
/COPY $PM211023.M.NEU,DATEN 1) 
/FSTAT DATEN 

0000006 :V: $PM1211034. DATEN 

«γΣ PUBLIC: 1 FILE.  RES- 6, FREE= 1, REL- O PAGES 
/COPY DAT,SPM211023. ASS. BEISPIEL2 | m 2) 
/FSTAT $PM211023. 

0000030 :V: $SPM211023. ASS. BEISPIEL2 

0000846 :V:$PM211023. DVS. BAND 

0000015 :V: $PM211023. DVS. BEISP. 3 

0000006 ΣΥ: $PM211023. DYS. BEISP. 5 

O000006 :V: $PM211023. M. NEU 

οὓς S PUBLLIES 5 FILES. RES- 903, FREE- 8, REL= 3 PAGES 


1) The file M.NEU with the user ID $PM211023 is copied to the file DATEI. 
2) The file DAT is copied to the file ASS.BEISPIEL2 with the user ID 


$PM211023. The file ASS.BEISPIEL2 vas previously cataloged with 
SHARE=YES. 
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File generation groups (FGG or DGG) and file generations 


/FSTAT DGG1,ALL 
0000000 :V: $PM211023.DGG1 (FGG) 


SHARE = NO ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 BACKUP# = 000 LARGE = NO BACKUP = 
DESTROY = NO AUDIT = NONE 
GEN = 00005 BASE = 00000 LASTGN = 00005 FIRSTGN = 
DISP = CYCLE 

: V2. PUBLIC: 1 FILE. RES= O, FREE= 0, REL- 

/CAT DGG2,GEN=5 

/COPY DGG1,DGG2 

/FSTAT DGG2,ALL 

0000000 :V: $PM211023.DGG2 (FGG) 
SHARE = NO ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = OOO BACKUP# = ODO LARGE = NO BACKUP = 
DESTROY = NO AUDIT = NONE 
GEN = 00005 BASE = 00000 LASTGN = 00005 FIRSTGN = 
DISP = CYCLE 

ΣΥ: PUBLIC: 1 FILE. RES= 0, FREE= O, REL- 


The file generation group DGG1 with GEN=5 is copied to DGG2. Prior to 
DGG2 must be cataloged with the same GEN value (GEN=5). 


/FSTAT DGG2,ALL 
0000000 :V:$PM211023.DGG2 (FGG) 


SHARE = NỌ ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 BACKUP# = 000 LARGE = NO BACKUP = 
DESTROY = NO AUDIT = NONE | 
GEN - 00005 BASE - 00000 LASTGN = 00005 FIRSTGN = 
DISP = CYCLE 

:V: PUBLIC: 1 FILE. RES= O, FREE= O, REL= 


/COPY DGG2,DGG3 


% DMSO6D8 GENERATIONS DO NOT HAVE SAME ATTRIBUTES. COMMAND TERMINATED 


/CAT DGG3,GEN=5 
/COPY DGG2,DGG3 
/FSTAT DGG3,ALL 
0000000 :V:$PM211023.DGG3 (FGG) 


SHARE = NỌ ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 BACKUP# = 000 LARGE = NO BACKUP = 
DESTROY = NO AUDIT = NONE 
GEN = 00005 BASE = 00000 LASTGN = 00005 FIRSTGN = 
DISP = CYCLE 

sve PUBLIC: 1 FILE. RES= O, FREE= O, REL= 


The file generation group DGG2 already exists and 
In order for DGG2 to be copied to DGG3, the group 
generation groups must tally. 
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/FSTAT DGG1,GEN-YES 

0000000 :V:$PM1211034.DGG1 (FGG) 
0000003 :V: $PM211034.DGG1(*0001) 
0000003 :V:$PN211034. DGG1( *0002) 
0000003 :V:$PN211034. DGG1( *0003) 
0000003 :V: $PM211034. DGG1( *0004) 
0000003 :V:$PN211034. DGG1( *0005) 
sVe μιας: 6 FILES. RES- 15, FREE= 10, REL= Ό PAGES 
/COPY DGG1,DATEI1 

/FSTAT DATEI1,ALL 

0000006 :V: $PM211034. DATEI1 


FCBTYPE = SAM VSNTYPE = PUB LASTPG = 0000005 2ND ALLO- 00009 
SHARE = NO ACCESS = WRITE 
ACCESS# = 001 CRDATE = 85-03-21 EXDATE = 85-03-21 LADATE = 85-03-21 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 001 BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE 
BLKTYPE = STD BLKSIZE = 002048 RECFORM = (V,N) RECSIZE = 00000 
VSN/DEV/EXT = PUBV11/D3475/002 2 
EXTONIS. ο... 2 
:V: PUBLIC: 1 FILE. RES= 6, FREE= 1, REL= 0 PAGES 


The file generation group DGG1 contains 5 SAM file generations with matching 
file attributes (record and block Length, record format etcs). They are 
copied together to the file DATEI1 by means of the COPY command. 


/COPY DGG1(*2) ,DGG2( *6) 

/FSTAT DGG2,GEN=YES 

0000000 :V:$PM211023.DGG2 (FGG) 

0000009 :V:$PM211023. DGG2( *0002) 

0000012 :Y:$PM211023. DGG2( *0003) 

0000012 :V:$PN211023. DGG2(*0004) 

00000085 :V:$PN211023. DGG2( *0005) 

0000009 :V:$PN211023. DGG2( *0006) 

ye "PUBLIC: 6 FILES. RES- 48, FREE- 3, REL- O PAGES 


The COPY command generates the file generation DGG2(*6) as a copy of file 
generation DGG1(*2). 


Example 4: 9 


/COPY DATEI,DATEI. KOPIE,WRITE=NEW 1) 

%  DMSOS18 FILE :V:$PM211034.DATEI.KOPIE ALREADY EXISTS. OVERWRITE? REPLY (YESzY; NO=N)? 
Y 

/COPY DATEI,DATEI. KOPIE,WRITE=NEW 2) 

^ DMSO518 FILE :V:$PM211034.DATEI. KOPIE ALREADY EXISTS. OVERWRITE? REPLY (ΥΕ5ΞΥΣ ΝΟΞΝ)Τ 
N 

* DMSO519 COPY COMMAND WITHDRAWN BY CALLER 

/COPY DATEI,DATEI.KOPIE,WRITEZNEW,DIALOGZNO | ——————————————————————— 3 

% DMSO51A FILE :V: $PM211034.DATEI. KOPIE ALREADY EXISTS. COMMAND TERMINATED 

/COPY DATEI,DATEI.KOPIE,WRITE-NEW,DIALOG-YES 

%  DMSOS18 FILE :V: $PM211034.DATEI. KOPIE ALREADY EXISTS. OVERWRITE? REPLY (YES=Y3 NO=N)7 
N 

*  DMSOS19 COPY COMMAND WITHDRAWN BY CALLER 

/COPY DATEI,DATEI.KOPIE,WRITE-REPLACE,DIALOG-YES 

/COPY DATEI,DATEI.KOPIE,WRITE-REPLACE,DIALOG-NO 

/COPY DATEI,DATEI.KOPIE 


1), 2) Message DMSO518 is displayed. 
3) Message DMSOS18 is suppressed. Message DMSO51A is displayed. 
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DROP CANCEL HOLD STATUS FOR TFT ENTRY 


The DROP command cancels the HOLD status imposed by the HOLD command on an 
entry in the Task File Table (TFT). If a RELEASE command (or REL macro) was 
pending for this entry, it is now processed, i.e. the TFT entry is deleted 
in accordance with the specification in the RELEASE command or REL macro, 
and the private devices associated with it are released. 


Operation Operands 
DROP [tink] 
Link This operand specifies the file Link name, i.e. the name of 


the Task File Table entry for which the HOLD status has been 


6 canceLed. 
If this entry is omitted, the first TFT entry vith the 
LINK name C' ccc cw." is processed. 


For examples see the HOLD command. 
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ERASE = ERASE FILE 


The ERASE command enables the user to erase his oun files, file generations, 
file generation groups or temporary files (data and catalog entries) and to 
release the space they occupy. He can also request a Listing of the names of 
the erased files. 


The command processes fully and partially qualified file names. 


Operation 


ee 
ER 


Operands 


pathname 
* 

prefix 
*SYSLST 
*SYSLSTnn 
*SYSOUT 
*SYSOPT 


DESTROY 
DATA 

y ] 
SPACE 
CATALOG 


ΝΕΟΙ 
C,LIST= 1 
YLESJ 


ALFTER] 
C,POS= ] 
BLEFORE] 


C,VOLUME=vsn] 


suserig. Cfivenene) | 


“pathname” stands for: [suseria. Cfitenane: 


catid 


userid 


filename 


filename 


This operand denotes the catalog identifier associated with 
the file. If no entry is made, the default catalog ID 
assigned to the user ID is assumed. 


This operand denotes the user identification. If no entry 
is made, the user's own user ID is assumed. Only the user's 
own user ID is permitted. 


This operand specifies which files are to be erased. The 
specification can be a fully or partially qualified file 
name, or the name of a temporary file, of a file generation 
or of a file generation group. 


If the name of a file generation is specified, the POS 
operand must also be specified. 


This operand refers to the job's EAM object module file, 


which is created and used by the Language processor. 
ALL other operands of the ERASE command are ignored. 
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prefix 


*SYSLST 
kSYSLSTnn 
*SYSOUT 
*SYSOPT 


DESTROY 


DATA 


SPACE 


CATALOG 


LIST-NLOJ 


-YLES] 


POS- 


ERASE 


This operand denotes a special character used a prefix (cf. 
section 2.1.1). The character is defined via the class 2 
option at system generation time. If "YES" is entered in 
response to the message "DMSD516 ERASE ALL FILES 

S. IMP. nnnn. ? REPLY (Y/N)", all temporary files are deleted. 


These system files can be erased (00<nn<99). In the case of 
*SYSOUT and *SYSOPT, the ERASE command is rejected if the 
system file to be erased does not have its primary 
allocation. 


Notes: 


- If the *SYSLST, *SYSLSTnn, *SYSOUT or *SYSOPT operand is 
specified, all other operands in the ERASE command are 
ignored. 

- The operand *SYSOUT is applicable in batch mode only. 

If an ER *SYSOUT is followed immediately by a LOGOFF 
command, no new SYSOUT file is created for the LOGOFF 
Listing. 


This operand specifies that the space occupied by the file 
"fiLename" is released, the catalog entry of the file(s) 
deleted and the data overwritten with binary zeros. 


This operand specifies that the data in "filename" is to be 
Logically deleted, i.e. the user will no Longer be able to 

reference the data since he is not allowed physical access 

to volumes. 


The individual file remains cataloged and the space 
aLLocated. 


In this case, the form of the catalog entry is identical 
to the entry made via a FILE command for a file that has not 
been opened before. 


This operand releases the space allocated to "filename". 
The individual file remains cataloged, but is treated as 
Logically deleted. 


This operand is not valid for private disks, and is 
rejected. 


This operand specifies that the catalog entry for 
“filename” is to be deleted. 


The CATALOG operand can be used only for files, file 
generations or file generation groups on private volumes. 


The names of the deleted files are not Listed. 


This operand specifies that the names of the deleted files 
are to be written in alphabetical order to SYSOUT. 


This operand is effective only when "filename" is the name 
of a file generation; it causes deletion of one or more 
generations. The generation number of the oldest (FIRST) 
and/or the most recent file generation (LASTGN) is adapted 
to the altered situation, if applicabLe. 
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=ACFTERJ This operand specifies deletion starting at the relative or 
absolute generation number specified in "filename". The 
generation specified by "filename" must exist, and is not 
deleted. 


=BCEFOREI This operand specifies deletion as far as the relative or 
absolute generation number specified in "filename". The 
generation specified by “filename” must exist, and is not 
deLeted. 


VOLUME-vsn This operand is valid only for private volumes in con- 
junction vith the operand CATALOG. 


It deletes all catalog entries for files whose catalog 
entries contain an entry referring to this volume. A 
function with the opposite effect is contained in the 
IMPORT command. 


When a volume containing generations of a file generation 
group is exported, gaps may arise in the file generation 
group; refer to the notes for the IMPORT command. 


Note: 
A file name entry in these operands is optional. 


Notes: 


- If the operands DESTROY, DATA, SPACE and CATALOG are not specified in the 
ERASE command, the space allocated to the file is released and its 
catalog entry deleted. 


- For files with the entry ACCESS=READ in the catalog (see the CATALOG 
|» command), only the catalog entry can be deleted, i.e. in the ERASE 
command onLy the CATALOG operand can be specified. 


- If a file on a private disk is to be deleted, the device on which that 
disk is mounted is requested for the job. After execution of the ERASE 
command, the device is returned to the system. 


- For files on private disks, the following volumes must be mounted at 
command execution time: 


- all volumes belonging to the file, if the DESTROY operand is specified 
- in the ERASE command; 


- the first volume, if the DATA operand is specified; 


- none of the volumes belonging to the file, if the CATALOG operand is 
specified in the ERASE command. 


These rules also apply if several files are referenced in the ERASE 
command via a partially qualified file name. In this case, the volumes 
for all the files concerned need not be mounted simultaneously. The 
system is requested to provide no more than the number of devices that 
are required for the file occupying the most volumes. 


- If an error occurs during deletion of a file generation group or a number 


of file generations in a group, the remaining file generations are not 
deleted, and the catalog entry for the file generation group is updated. 
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- In a procedure file there is no need for a STEP command to follow erasure 
of the object module file (/ERASE *), since the ERASE command does not 
produce an error message if this file is empty. 


- If a file does not exist, the DMS sends a message to the symbolic system 
file SYSOUT, and continues by processing the next command. In DO procedures 
a branch is made to the next STEP command. 


- Although S.IN... files generated by the system are passvord-protected 
(EXPASS), they can still be erased by means of the ERASE command without 
first specifying the password. In this vay S.IN... files that are no 
Longer required or have.not been erased by the system can be removed 
from the system. 


- In addition to the catalog entry on the private disk, a private file can 
have a corresponding catalog entry on one or more pubsets. However, when 
the ERASE command/macro is executed, onLy the cataLog entry on the pubset 
referenced by the catalog identifier (explicit specification or default 

6 catalog ID) is erased, i.e. catalog entries for the now erased file 
continue to exist on other pubsets. 


Network catalog management (see also the "MSCF Multiprocessor System" 


manual) 


The user can specify only his own user ID, but any valid catalog identifier. 


U805-J-Z55-5-7600 3*27 


ERASE 


Example 1: 
The following Listing is produced in interactive mode: 


/FSTAT M. PROC. 4 

0000087 :V:$PM1211034. M. PROC. 4 

;V3 πας. A FILE. REGS 87, FREE- 1, REL= 0 PAGES 
JER M. PROC. ———————————————————— 1) 
/FSTAT M. PROC. 4 

* | DMSO533 REQUESTED FILE NOT CATALOGED ON PYS V. CMD TERMINATED 

JER M. PROG» ,LISTsYES .:————————— MM 42) 
DMSO516 ERASE ALL FILES :V:$PM211034.HM.PROC.7 REPLY (Y=YES; ΝΞΝΟ)Τ 


DMSO800 ERASE FILE :V:$PM211034. M. PROC. ENDP 
DMSO800 ERASE FILE :V:$PM211034. M. PROC. ENDP-SKIP 
DMSO8GO ERASE FILE :V:$PM211034. M. PROC. NAME 
DMSO800 ERASE FILE :V:$PM211034. M. PROC. 3 
DMSO800 ERASE FILE :V:$PM211034.M. PROC. 3.1 
DMSO800 ERASE FILE :V:$PM211034.M. PROC. 3. 2 
/FSTAT M.PRIM.FOR,S 
0000087 :V: $P211034. M. PRIM. FOR 

FCBTYPE - ISAM VSNTYPE - PUB LASTPG = 0000086 2ND ALLO- 00012 
:V: PUBLIC: 1 FILE. RES= 87, FREE= 1, REL= Ὁ PAGES 
/ER M.PRIM.FOR,DATA | ———————————————————————————————— 3) 
/FS M. PRIM.FOR,S 
0000087 :V:$PM211034.M. PRIM. FOR 

FCBTYPE - NONE VSNTYPE - PUB LASTPG 0000000 2ND ALLO- 00012 
:V: PUBLIC: 1 FILE. RES= 87, FREE= 87, REL= 87 PAGES 
IERM = ὦ} 
% DMSO516 ERASE ALL FILES :V:$PM211034.M.7 REPLY (Y=YES; ΝΞΝΟ)Τ 
Y 
% DMSO801 ERASE ERROR ON FILE :V:$PM211024. M. ΚΟΡ. SAM 
X  DMSOSC3 FILE TO BE ERASED IS IN USE. COMMAND TERMINATED 


δε 28 ας οἱ αξ δξ -ς 2 


/FSTAT M. 
0000051 :V:$PMN211034. M. KOP. SAM 
Vs PUBLIC: l FILE. KRESS o1, FREE- 1, REL= O PAGES 


/FSTAT DGG1,GEN=YES 

0000000 :V:$PM211023.DGG1 (FGG) 

0000008 : V: $P4211023. DGG1 ( *0001) 

0000009 :V:$PM211023. DGG1( *0002) 

0000012 :V:$PM211023. DGG1( *0003) 

0000012 :V:$PM211023. DGG1( *0004) 

0000008 :V:$PM211023. DGG1( *0005) 

:V: PUBLIC: 6 FILES. RES- 45, FREE= 4, REL- Ὁ PAGES 
JER DGG1(*3) ,POS=BEFORE | ——————————————————————————————————— s) 
/FSTAT DGG1,GEN=YES 

0000000 :V:$PM211023.DGG1 (FGG) 

0000012 :V:$PM211023. DGG1( *0003) 

0000012 :V:$PM211023. DGG1( *0004) 

0000006 :V:$PM211023. DGG1( *0005) 

:V: PUBLIC: 4 FILES. RES= 30, FREE= 3, REL= ο PAGES 


/ER DGG1(*3) ,POS=AFTER 6) 
/FSTAT DGG1,GEN-YES 

0000000 :V:$PM211023.DGG1 (FGG) 

0000012 :V:$PM211023. DGG1( *0003) 

Vs- PUBCEE: 2 FILES. RES= 12, FREE= 1, REL= O PAGES 
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1) The file M.PROC.4 is deleted; its storage space (3 PAM blocks) is 
released and its catalog entry deleted. 


2) A partially qualified name has been specified in this ERASE command, 
with the result that several files, namely all those whose names begin 


with "M.PROC.", are deleted. A List of these files is displayed on the 
terminal (SYSOUT). 


3) The data in file M.PRIM.FOR is deleted, but the file's storage space is 
not released, as is shown by the subsequent FSTATUS command. 


4) An error message is issued for files which cannot be deleted. These two 
files cannot be deleted until: 


1. the access authorization for the file M.KOP.SAM is changed to 
ACCESS=WRITE: 


/CATALOG M. KOP. SAM,STATE=UPDATE,ACCESS=WRITE 


© 2. the password required for the file M.VORH is entered with the 
PASSWORD command. 


5) ALL file generations prior to DGG1(*3) are deleted. DGG1(*3) is now 
the oldest generation of file generation group DGG. 


6) ALL file generations subsequent to DGG1(*3) are deleted. DGG1(*3) thus 
becomes the Latest file generation of DGG. ! 
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Example 2: 


The command "ERASE A." is to reference two files: 

file A.1, which is resident on two private volumes, and file A.2, which is 
resident on three private volumes. The ERASE command then requests three 
devices (not 5), since for file A.1 two devices, and then for file A.2 three 
devices need to be mounted simultaneously. 


Device 1 Device 2 Device 3 


: 


T 
est. UC 


Fig. ER-1: Deleting files on private volumes 
In the case of deletion accompanied by the release of storage space, the 


number of devices required is thus equal to the number of volumes belonging 
to the file occupying the most volumes. 
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FILE DEFINE FILE ATTRIBUTES 


The file command is used to define files (and file generations) and their 3 
attributes. ALL files except EAM files must first be defined by this command 

(or the FILE macro). The file is thereby cataloged and the specified 

attributes then remain known to the system. There is therefore no need to 

repeat these attributes in a FILE command when the file is to be referenced 

again. 


Principal functions of the FILE command: 
- Catalog a new file or file generation (see the "filename" operand). 


- Generate an entry in the Task File Table TFT (see the LINK operand and 
Fig. FILE-1). 


e - Request devices and volumes (see the operands DEVICE and VOLUME). 


- Cause console messages requesting the mounting of private volumes (see 
the MOUNT operand). 


=-= AlLocate and deallocate storage space on disks (see the SPACE operand). 


- Allow processing of non-cataloged files or file generations on private 
voLumes (see the STATE-FOREIGN operand). 


- Provide information regarding data organization on tapes (see the LABEL, 
TPMARK, CODE operands). 


- Specify a file retention period (see the RETPD operand). 
- Specify the "OPEN mode" (see the OPEN operand). 


- Specify the data structure for the various access methods. 


Operands Access method: 


SAM ISAM 
- FCBTYPE 


RECF ORM 
RECSIZE 
BLKSIZE 
SHARUPD 
KEYLEN 
KEYPOS 
` DUPEKY 
LOGLEN 
VALLEN 
VALPROP 
OVERLAP 
PAD 
WROUT 


-y 
> 
ol 


«κκ 


H- μ.μ. P- μ. μ. μ. μ. H-X μ.μ. HX 


X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 


where: 


i: ignored but not rejected, since in certain cases ISAM or SAM files 
can be accessed vith PAM (see section 6.2). 
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- Request private devices and volumes, and also storage space for the file 
data section of ISAM files if this is to be separated from the file index 
section (see the operands DDEVICE, DVOLUME, DSPACE). 


DEVICE 
VOLUME Storage space 


reserved 


Cy que 
MOUNT message for 
private volumes c" 
Entry in the TFT 


ask File Table 


LINK - link Private devices and 
filename volumes reserved 


RECFORM 
RECSIZE 
BLKSIZE 


Catalog entry qu 
$userid.filename 
μπι. ΠΠ 


When the 

file is 

opened the TFT entry 
overwrites the FCB with 
the same LINK name 


*) In the source program the file link name (LINK) is specified as 

follows in the different programming languages: 

Assembler: FCB macro, LINK operand 

COBOL: First 8 characters of the name in the SELECT clause 
or the link name specified in the ASSIGN clause 

FORTRAN: DSET number (specified in the FILE command as 
DSETnn) 
DSN (specified in the FILE command as ALGOnn) 
File name of the FILE statement 
File name of the F card 


Fig. FILE-1: Functions of the FILE command 
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- FILE 
FILE DEFINE FILE ATTRIBUTES 


The file command is used to define files (and file generations) and their 
attributes. ALL files except EAM files must first be defined by this command 
(or the FILE macro). The file is thereby cataloged and the specified 
attributes then remain knoun to the system. There is therefore no need to 
repeat these attributes in a FILE command when the file is to be referenced 
again. 


Principal functions of the FILE command: 
- Catalog a new fi or file generation (see the "fiLename" operand). 


- Generate an entry in the Task File Table TFT (see the LINK operand and 
Fig. FILE-1). 


e - Request devices and volumes (see the operands DEVICE and VOLUME). 


- Cause console messages requesting the mounting of private volumes (see 
the MOUNT operand). 


- AlLocate and deaLLocate storage space on disks (see the SPACE operand). 


- Allow processing of non-cataloged files or file generations on private 
voLumes (see the STATE=FOREIGN operand). 


- Provide information regarding data organization on tapes (see the LABEL, 
TPMARK, CODE operands). 


- Specify a file retention period (see the RETPD operand). 
- Specify the "OPEN mode" (see the OPEN operand). 


- Specify the data structure for the various access methods. 


Operands Access method: 


SAM ISAM 
e FCBTYPE 


RECF ORM 
RECSIZE 
BLKSIZE 
SHARUPD 
KEYLEN 
KEYPOS 
` DUPEKY 
LOGLEN 
VALLEN 
VALPROP 
OVERLAP 
PAD 
WROUT 


ES 
D 
z3 


x< X X ὃ 


μ.μ. H- H- He H- H- H- H- X μ.μ. μ. X 


X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 


where: 


i: ignored but not rejected, since in certain cases ISAM or SAM files 
can be accessed vith PAM (see section 6.2). 
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- Request private devices and volumes, and also storage space for the file 
data section of ISAM files if this is to be separated from the file index 
section (see the operands DDEVICE, DVOLUME, DSPACE). 


DEVICE 


VOLUME Storage space 


Catalog entry (a nite) 
Suserid.filename 
on ὑπ 


reserved 


dip dub on disks 
MOUNT message for 
private volumes cm 
Entry in the TFT 


ask File Table 


LINK = link Private devices and 
filename volumes reserved 


RECFORM 
RECSIZE 
BLKSIZE 


When the 

file is 

opened the TFT entry 
overwrites the FCB with 
the same LINK name 


*) In the source program the file link name (LINK) is specified as 

follows in the different programming languages: 

Assembler: FCB macro, LINK operand 

COBOL: First 8 characters of the name in the SELECT clause 
or the link name specified in the ASSIGN clause 

FORTRAN: DSET number (specified in the FILE command as 
DSETnn) 

ALGOL: DSN (specified in the FILE command as ALGOnn) 

PL/I: File name of the FILE statement . 

RPC: File name of the F card 


Fig. FILE-1: Functions of the FILE command 
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Explanation of Fig. FILE-1: 
During processing of a FILE command, the system performs a number of 
functions, e.g.: 3 


- It creates a catalog entry for the specified file name, or, if the file 
has already been cataloged, uses the existing catalog entry. The system 
then transfers to this catalog entry the results of the device, volume 
and space reservations, which can be controlled via the DEVICE, VOLUME 
and SPACE operands. Entries in all other operands are ineffective if no 
LINK name is specified. 


- It makes an entry in the Task File Table (TFT) for the specified file 
Link name (LINK name). This entry includes the file characteristics, 
namely the values of the operands LINK, "filename", RETPD, OPEN, RECFORM, 
RECSIZE, BLKSIZE, KEYPOS, KEYLEN, PAD, LOGLEN, VALLEN, VALPROP etc., 
but only those which were explicitly specified. 


e The file characteristics in the TFT are not automatically transferred to the 

catalog entry upon processing of the FILE command. The TFT entries can take 
effect when the associated file is opened only if a program uses the same 
file Link name as the FILE command. When the file is opened, the system 
collects the file characteristics from three different sources: 


1. from the program's file definition (FCB); 


2. from the TFT entry with the corresponding file Link name provided by 
the FILE command; 


3. from the catalog entry created by the CATALOG, COPY, DATA, FILE, SYSFILE, 
or VERIFY command, or, in the case of preceding file processing, via a 
program. 


The specifications in the TFT entry, i.e. everything defined explicitly via 
a FILE command, overwrite any corresponding FCB entries which may exist when 
the file is opened. Entries relating to file characteristics which are in 
neither the FCB nor the TFT entry are then transferred from the file's 
catalog entry. 


e Note: 


For a file which already contains the appropriate information in its catalog 
entry, the operands FCBTYPE, RECFORM, RECSIZE, BLKSIZE, KEYLEN, LOGLEN, 
VALLEN and VALPROP can be specified in the form of "null operands", e.g. 
FILE..., FCBTYPE=, RECFORM=, RECSIZEz,.... This ensures that, when the file 
is opened, this data is always taken from the file's catalog entry, i.e. 
entries in the FCB have no effect. 
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Format for disk files 


Operation Operands 
FILE pathname 
L ! 1 
*DUMMY 


[,LINK=Link] 
C,DEVLICE] =devicel 
PRIVATE 
(PRIVATE,number) 
C,VOLCUMEJ =; . J 
vsn 
(νδῆρεεο) 
[ ,MOUNT=seqno] 
primary 
C,SPACE=L}j(primaryl,secondary]) [11 
(firstpage,amount,ABS) 
[L ,STATE-FOREIGNJ 
C,RETPD=days] 
INPUT 
OUTPUT 
EXTEND 
L ,OPEN-1REVERSE[] 
UPDATE 


OUTIN 
INOUT 


ISAM 
C,FCBTYPE=;SAM 1 
PAM 


C,RECFORM= 1 
F N 
fee fils 
U A 


C ,RECSIZE=recLlengthl 


STD 
C,BLKSIZE= 1 


(STD,integer) 
NO 
C ,SHARUPD= J 
YES 
C,KEYPOS=dispLacement] 


[,KEYLEN-keyLengthJ 
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FILE 


Operands 

L ,DUPEKY-YESJ 

C,LOGLEN=flag1] 

C,VALLEN=flag2] 
MIN] 

[L , VALPROP- 1 
MAX 

C,OVERLAP=YES] 


C,PAD=percent] 


NO 
[,WROUT- ] 
YES 


L ,DDEVICE-ddevicel 


vsn 
C,DVOLUME= J 


CVS piee?) 


primary 
[,DSPACE-j (primaryl,secondary]) [1 
firstpage,amount,ABS) 


YES 
[ , WRCHK- 
NO 


"pathname" stands for: [:catid:][$userid. ] filename 


catid 


userid 


filename 


*DUMMY 


This operand denotes the catalog identifier associated with 
the file. If no entry is made, the default catalog ID 
assigned to the user ID is assumed. 


This operand denotes the user identification associated 
with the file. If the operand is omitted, the user's own 
user ID is assumed. | 


This operand specifies the fully qualified name of a file 
or the name of a file generation or of a temporary file, to 
which all the other operands in the FILE command refer. The 
name of a file generation group must not be specified. 


If, at this stage, the file or file generation has not 
yet been cataLoged, this is nov performed. 


This operand defines the dummy file. This specification 
allows input and output operations to be simulated in the 
program. 


1. Input: If a program attempts to read this dummy file, 
the program's end-of-file routine is activated, 
i.e. as though the file had already been read. 
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LINK=Link 


DEVICE=device 


2. Output: If an attempt is made to write to the dummy 
file, the data is still transferred to the 
program's buffer areas (IOAREA), but buffer 
output to a volume does not take place. 


If the DUMMY operand is used, all the other FILE command 
operands -- except LINK -- are checked for syntax errors 
but are otherwise ignored. Therefore no device assignment, 
storage space allocation or cataloging is performed for the 
dummy file. 


This procedure can be used for program test runs, or if 
an output is to be temporarily skipped. 


This operand specifies a file Link name not exceeding 8 


bytes. The assignment of Link names is governed by the 

same rules as for the use of file names (cf. section 2.1.2). 
If omitted, no TFT entry is made. An entry is made under 
this name in the Task File Table (TFT). If the Link name 
already has a TFT entry at this time, the Latter is 
replaced by the new TFT entry. If devices were connected 
with the old TFT entry, this connection is now dissolved, 
though the devices are still available to the Job. 


This operand specifies the device type. The following can 
be entered for "device": 


Device For disk storage unit Device code 
D3455 3455 A8 
D5881 

D3465 3465 A9 
D5882 

D3468 3468 AA 
D3470 3470 ΑΒ” 
DS804 

D3475 3475 AB 
D3480 3480 AC 
D348E 348E AD 


Default value: 
If the DEVICE and VOLUME operands are omitted from the FILE 
command, a device for a public volume is assumed. 
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VOLUME=PRIVATE This operand specifies that the operator must mount private 
volumes. These volumes include those disks which do not 
have to be permanently connected to the system, i.e. are 
not public volumes. As soon as a private volume is 
assigned, it beLongs to the user. 


-(PRIVATE,number) 
This operand defines the desired number of private voLumes, 
where "number" is an integer in the range 1 through 9. 


-vsn This operand specifies the volume serial number (not 
exceeding 6 bytes) which serves to identify volumes. A 
maximum of 100 volume serial numbers can be specified, 
separated from each other by commas and enclosed in 
parentheses. 


With disk files, the system attempts to satisfy the 

Space requests (see the SPACE operand) on the first volume 
e specified. If this is successful, the other volume serial 

numbers specified are also entered in the catalog (for 

future extensions of the file). 


Note: 


If “pathname” is the name of a file generation on 
private volumes, and DISP=REUSE (see the CATALOG command) 
was specified for the associated file generation group, 
the entries in the VOLUME operand are ignored when the 
maximum permissible number of cataloged file generations 
has been reached (see the GEN operand in the CATALOG 
command). If file generation "pathname" replaces an 
existing generation within its file generation group, it 
also adopts the Latter's private volumes. 


If a private file that is already mounted is to be 
extended to incLude another vsn, a primary allocation 

+ O must be simultaneously specified with SPACE. Otherwise, 
the FILE command will be ignored. 


If a FILE command with the VOLUME or SPACE operand is 


© | specified for a file which is currently open, it will 28. 
rejected. 
MOUNT=seqno This operand mounts the file's private volumes. A MOUNT 


message is displayed at the console. 

For example, the sequence number 2 designates the second 
entry in the file's volume table, which may contain each 
vsn once only. 


Default value: If the operand is omitted, the volume on 
which the file begins is requested. 


MOUNT=0 

A volume request is not carried out until the file is 
opened, provided it exists and the operands DEVICE, 
VOLUME, SPACE and DSPACE are not specified. 
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SPACE= 


=primary 


This operand specifies changes in storage space allocation 
for disk files: 


- the primary allocation "primary" stipulates how much 
space is to be allocated to the file initially; 


- the secondary allocation "secondary" determines how much 
space is to be allocated automatically if additional 
space is required in the course of file processing; 


- the absolute allocation "(firstpage,amount,ABS)" gives 
the user the additional option of specifying physical 
page numbers on the volume in the case of files on 
private disks. 


AbsoLute and non-absoLute aLLocation can be specified 
in any order for a private disk file. 


If the SPACE operand is omitted, the system default 
allocation becomes effective (as defined at system 
generation time). 


If a FILE command with the operand VOLUME or SPACE is 
specified for a file which is currently open, it will be 
rejected. 


If a storage space request for public volumes causes the 
maximum value specified in the JOIN entry of the user ID to 
be exceeded, the request will be rejected or only partly 
honored (message DMSO54A, but not if SPACE=ABS is 
specified). If the user ID is expressty authorized 
(enforcement) to exceed this maximum number of PAM bLocks, 
however, there is merely a warning message. 


Both primary and secondary allocation must be either 
greater than or equal to the specified buffer Length 
(see the operand BLKSIZE). 


In order to reduce system administration overheads, the 
following should be considered when selecting the values 
for primary and secondary allocations: 


- primary allocation should correspond to the estimated 
size of the file to be set up. 


- A minimum of 9 to 15 PAM blocks should be selected for 


secondary allocation. 


- For Large files the values for primary and secondary 
allocation should be selected as multiples of the 
management units packet (= 24 PAM blocks) or segment 
(= 192 PAM blocks). 


If necessary, the number "primary", the primary 
allocation, is rounded up to a multiple of 3. 


Positive number specifications define the number of 


PAM bLocks (2048 bytes) which are to be marked as reserved 
for the file (in addition to any space already reserved). 
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Negative number specifications can be made for files 

under the user's own user ID to which space has already been 
allocated. The system then attempts to release Space. The 
greatest vaLue that can be specified is 9999999. 
Specifications in the VOLUME operand are ignored. The 
remaining file size is at the same time a multiple of 3 

and of the buffer size. 

ReLease of storage commences on the Last volume entered in 
the catalog and continues until either the specified number 
of PAM blocks "primary" has been released, or a PAM block 
which contains data is encountered (applies to ISAM and 
SAM). Thus, deallocation starts at the end of the file and 
proceeds backwards towards the start of the file. ISAM file 
storage space cannot be released separately for the data 
and index sections (see DSPACE). 

In the case of files on private disk, at Least 3 PAM blocks 
remain allocated. 


© =(primary,secondary) 

The secondary allocation ("secondary") specifies the 
number of PAM blocks (2048 bytes) to be reserved for the 
file whenever more storage space is required (dynamic 
allocation). 

If necessary, this number will be rounded up to a multiple 
of 3 when the reservation takes place. 
Maximum value for "secondary": 32767. 


A zero primary allocation means that no further storage 
Space is to be allocated with the FILE command. This 
specification is required, for example, if the user wishes 
to change only the value of the secondary allocation for 
the file but not the current space allocation. If 
"filename" does not yet exist, zero is not permitted as 
the primary allocation on private disks. 


The secondary allocation for a file is recorded in its 
catalog entry and can be changed at any time. 


A zero secondary allocation suppresses dynamic 
allocation. This specification remains effective until 
© a new secondary allocation is specified. 


Storage space requests made with SPACE=(primary, secondary) 
refer to the whole file, i.e. not to a particular volume. 


1. ALLocation of storage space for new files 


If several volume serial numbers are specified in the 
VOLUME operand for a file for which space is being 
allocated for the first time, the system attempts to 
reserve all the space on the first volume. 

If this is successful, the other volume serial numbers 
are entered in the catalog (for further extensions). 
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2. Extension of storage space allocation for files 
on pubLic disks 


With these files, the system first attempts to allocate 
space on the Last volume of the file. 

If this is inadequate, the system attempts to reserve 
the space on the volume with the most free space. (To 
be precise, the pubLic disk vith the highest percentage 
Of free packets is seLected, a packet being 24 con- 
tiguous PAM bLocks. ) 


3. Extension of storage space aLLocation for fiLes 
on private disks 


If the user specifies no volume serial numbers in the 
VOLUME operand, the system attempts to reserve space on 
the Last volume of the file. If this is inadequate, the 
space is sought on other private disks entered in the 


cataLog. 9 
If the user does specify volume serial numbers in the 
VOLUME operand, the system attempts to reserve space on 
the specified volumes. If this is inadequate, a partial 
assignment is made. Any space on disks whose volume 
serial numbers are entered in the catalog but do not 
appear in the current FILE command, is ignored. 

If a file, previously cataloged only on a private disk, 
is to extend over a second private disk, the operands 
VOLUME, DEVICE and SPACE must be specified. If the 
operand SPACE is not specified, the FILE command wilt 
be ineffective. 


=(firstpage,amount,ABS) | 
| This operand is accepted for private disks only. 
This value for the SPACE operand is meaningful only if a 
vsn is specified in the VOLUME operand at the same time. 


ABS specifies that an absolute allocation is to be 
made. If this is the first allocation for a file, the 
value of the secondary allocation is set to zero. 


The entry firstpage specifies the physical block (2048 
bytes) at which the allocation is to start. Since only Ω 
multiples of 3 can ever be requested, the entry "firstpage" 

must contain the vaLues 1, 4, 7, etc., i.e. the entry 

"firstpage" divided by three must always Leave a remainder 

of 1. 


The block with which reservation can begin is determined 
by disk initialization. 


The entry amount defines the number of PAM bLocks to 
be requested. This value must be a multiple of 3. 


An absolute allocation is made only if the whole of the 


area requested can be reserved for the file, i.e. partial 
assignments are not possible. 
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In the case of absolute allocation, only one volume can be 
referenced per FILE command. If the user has specified more 
than one vsn in the VOLUME operand, only the first vsn is 
used. If space is to be allocated on several (n) volumes, 
the FILE command must then be issued n times. 


Types of disk storage unit with specified capacities: 


Disk 3455| 3465 3468 3470 3475 3480 
Storage 5881| 5882 5804 

Unit 

(type) 


30774|61473|130242| 202908 183246] 225663| 451605 


x) Data blocks without spare cylinder, standard Labels 
and system-resistent blocks (SYSIPL). 


STATE=FOREIGN This operand specifies that an existing non-cataLoged file 
on private volumes is to be cataloged. This file may have 
been: 


- previously deleted from the catalog by the ERASE 
command (CATALOG operand) or 

- created in a different BS2000 computer center, or 

- created under a different operating system. 


If “filename” is a file generation, it should be noted 

that the catalog entry for the associated file generation 
group must be present and thus, if necessary, must first be 
restored by means of the CATALOG command. 

The following should be noted with regard to 

STATE=FOREIGN: 


For files on private disks with the specification 

© STATE=FOREIGN, the first vsn for the file will be 
specified and only the first volume for the file need be 
mounted when the file is opened. The system then takes 
the file attributes from the F1 Label and enters them 
in the catalog. The F1 Label contains the user ID of the 
file's creator, which must be present in the JOIN file 
of the operating system in order to allow cataloging of 
the FOREIGN file via the FILE command. 


If the user issuing the FILE command for the FOREIGN file 
is not the creator of the file, he must specify in his 
FILE command the complete file name, including the user ID 
of the file's creator. In addition, the creator must, in 
this case, have cataloged the FOREIGN file as shareable 
(SHARE=YES in the CATALOG command), in order to permit 
access under another user ID. 
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RETPD=day 


OPEN= 


FoBTYPE| 
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Files on private volumes which, with the specification 
STATE=FOREIGN, are taken over into a different operating 
system or entered in a different user's catalog must be 
deleted from the catalog of the old system or of the owner 
(ERASE command vith the CATALOG operand). For if the five 
is modified in the neu system, and an attempt is sub- 
sequently made to access the file with the old catalog 
entry, probLems may arise with the possible result that 
none of the files on the private volume can continue to be 
used. (This does not apply to shareable private disks.) 


This operand specifies the file retention period in days, 
during which time the file can be read only. 

"days" must be a decimal integer, the maximum value of 
which is calculated from the difference in days between the 
end of the century (31.12.99) and the current date. 

This retention period can be specified only for files to 
be cataloged for the first time. 

When the retention period has expired, the file can be 
updated, but it is not automatically deleted. 

RETPD>O has no effect for temporary files. 

Default value: zero days, i.e. the file can be updated 
immediateLy. | 


This operand specifies the mode in which the file is to be 
opened. This entry can, however, be overwritten by the 
operand in the OPEN macro when the file is opened. 


No FILE command vith the operands VOLUME and DEVICE can 
be given for files on private disk that are opened in 
INPUT mode. 


The following table indicates the possible specifications 
for the OPEN operand in accordance vith the various access 
methods for disk files: 


The individual OPEN modes are discussed under the 
corresponding access methods. 


This operand specifies the access method with which the 
disk file is to be processed. 
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ΕΕΟΕΟΡΒΗΞΥ This operand specifies variable-Length records, i.e. each 
data record starts with a 4-byte record Length field in 
which the record Length is entered. 
=F This operand specifies fixed-length records. 
=U This operand specifies records of undefined Length, i.e. 


the record Length must be defined at input/output time. 
This is not allowed with the ISAM access method. 


The following additional entries can be made: 


"A" specifies that the first data byte is an ASA printer 
control character (print with SPACE=E). 


"M" specifies that the first data byte will be interpreted 
as a control character in EBCDIC (print with SPACE-E). 


e "N" specifies that there is to be no printer control 
character (SPACE-E must not be used vhen printing out. 


When using the PAM access method, the RECFORM operand can 
be specified but the system will ignore it. 


RECSIZE-recLength 
This operand specifies the Length in bytes for fixed-Length 
records (RECFORM=F). 


For variable-Length records (RECFORM=V), this operand 
specifies the maximum permissible Length for a record, 
including its 4-byte control field. With variabLe-Length 
records, it is not mandatory to specify RECSIZE; the 
system initially assumes the maximum possible record 
Length is equal to the buffer Length (BLKSIZE). 
If the record Length is undefined (RECFORM=U), the RECSIZE 
operand specifies one of the general-purpose registers 
2 through 12, which is to contain the record Length for 
input/output. As soon as a format-U record is read, the 
system supplies the general-purpose register with the Length 
specification for this record. If such a record is to be 
e written, the user must provide the Length specification in 
the specified general-purpose register. 


When using the PAM access method, the RECSIZE operand can 
be specified but the system will ignore it. 


BLKSIZE-STD This operand specifies a 2048-byte buffer (one PAM block) 
for input/output involving the file. Data transfer to and 
from the I/O devices thus takes place in units of this size. 


=(STD,integer) 
This operand specifies that the buffer Length is a multiple 
of 2048 bytes (one PAM block). "integer" defines the 
number of PAM pages and must not exceed 16, i.e. the 
maximum buffer size is 32768 bytes. 


If the "integer" entry is green than or equal to 2, 
the following applies: 


- Primary allocation operand SPACE): 


"primary" 2 (2 * "integer") for SAM files 
"primary" 2 (2 * "integer") + 1 for ISAM files 
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SHARUPD=YES 


KEYLEN-keyLength 


ExampLe: 
BLKSIZE-(STD,8) --» "primary" 2 18 (SAM) 
BLKSIZE-(STD,6) --» "primary" 2 15 (ISAM) 


- Secondary allocation (operand SPACE): 
"secondary" 2 "integer" for SAM and ISAM files 


ExampLe: 
BLKSIZE=(STD,8) --» "secondary" 2 9 


For UPAM files processed vith chained I/0, both primary 
and secondary allocation must be as Large as the required 
number of PAM blocks transferred with each 1/0 operation. 


With ISAM files, a record must not exceed the Length 
(BLKSIZE-4). In the case of all other file types, the 
buffer Length BLKSIZE is the upper Limit for the record 
Length. 


Notes: 


- In the BLKSIZE operand, it is also possible to specify an 
absoLute value. However, it should be noted that the use 
of standard bLocks must be specified if the file vas 
created with standard blocks or with a block size n*STD, 
as no internal conversion from absolute value to a 
multiple of standard is performed. 


- In the case of SAM access and SETL processing: . 
When blocking is extensive, the buffer can hold only 
a maximum of 255 records. The Length of the positioning 
information is only 1 byte. 


This operand specifies that an ISAM or PAM file can be 
simultaneously updated by more than one job, i.e. the file 
is not Locked as soon as a job has opened the file in output 
mode. This results in an increased 1/0 rate. 

The WROUT function (WROUT operand) is thus activated. 


This operand specifies that this file can be used by more 
than one job simultaneously only if all jobs are operating 
in read mode. 


This operand specifies the record key Length in bytes for 
an ISAM file. Each record in the file must have this key 
Length. The key must not exceed 255 bytes. 

Default value: 8 bytes. 


KEYPOS=dispLacement 


This operand specifies the position of the first character 
of the record key. The key must be in the same position in 
every record of the ISAM file. If variabLe-Length records 
are specified (RECFORM=V), the 4-byte record Length field 
is considered to be part of the record. 

Default value: 5S for RECFORM=V, 1 for RECFORM=F. 
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DUPEKY=YES This operand specifies that duplicate ISAM keys are 
allowed. 


Default value: If duplicate keys are encountered, control 
is passed to a user program routine whose address was 
given in the program's EXLST macro. 


Note: 

The introduction of alternate keys will Lead to restrictions 
with regard to duplicate keys. These restrictions will 
affect files for which alternate-key functions are to be 
used. Consequently, the generation of files with duplicate 
keys (DUPEKY=YES in the FILE command) should be avoided 
wherever possible. 


LOGLEN-fULag1 This operand specifies the Length of the Logical flag for 
ISAM files. This flag, along with the ISAM key and the 
value flag, can form part of the ISAM record index. The sum 
6 of the Length entries in ΚΕΥΙΕΝ, LOGLEN and VALLEN must not 
exceed 255. 
Default value: Zero. 


VALLEN=fLag2 This operand specifies the Length of the value flag for 
ISAM files. This flag, along with the ISAM key and Logical 
flag, can form part of the ISAM record index. The sum of 
the Length entries in KEYLEN, LOGLEN and VALLEN must not 
exceed 255. 
Default value: Zero. 


MIN} This operand specifies how the value flag is to be 
VALPROP=| | propagated in the index of ISAM files on all index Levels 
MAX (value propagation). This entry allows the user to search 
the file more rapidly if the majority of value flags with 
ascending ISAM keys are rising or falling. 


Each index record contains the Lowest (MIN) or highest 
(MAX) value flag for the next Lower-Level block to which 
it is pointing. 


Note for LOGLEN, VALLEN and VALPROP: 

C In subsequent ISAM versions, the flag functions (Logical 
and value flags) will be replaced by alternate keys (i.e. 
multiple indices corresponding to the ANS-COBOL functions). 
As a result, flag processing (the LOGLEN, VALLEN and 
VALPROP operands) will not be developed further and should 
be avoided if possible. 


OVERLAP=YES This operand specifies that buffered or overlapped read 
operations are to be performed for ISAM if more than one 
data buffer exists. This applies to the ISAM macros GET and 
GETR. 


Default value: No attempt is made to perform overlapping 
I/O operations. Nevertheless, ISAM does use the second 
buffer area (IOAREA2), albeit as a work area. 


PAD-percent This operand specifies the percentage of the buffer Length 
| which is to be reserved for subsequent extensions (e.g. 
insertion or extension of records) during creation of an 
ISAM five. 
Default value: 15% of the data space is reserved. 
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WROUT=YES 


DDEVICE=ddevice 
DVOLUME=vsn 


This operand specifies that the data and index buffers of 
an ISAM file are to be written back to the volume 
immediately after a modification, thereby enhancing file 
security. However, this is necessarily accompanied by an 
increase in 1/0 activities. The WROUT function becomes 
effective after the ISAM macros STORE, ELIM, INSRT, PUTX 
and PUT (with PUT, only when the buffer is full). 


Writing back is not performed immediately, and possibly 
not until the file is closed. 


If SHARUPD=YES is specified for an ISAM file, this 
automatically includes the WROUT function, i.e. the 
WROUT operand becomes redundant. 


DSPACE-(primaryL,secondaryl) 
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While DEVICE, VOLUME and SPACE relate to the file index 
section of the ISAM file, these three operands relate to 
its file data section. In this vay, it is possible to 
create an ISAM file whose data and index blocks reside 
on different private disks. 


These operands are meaningful only when the ISAM file is 
created on a private disk. When associated with the 
operand FOREIGN, they will result in an error message. 


The operands DDEVICE, DVOLUME and DSPACE are specified 
in exactly the same way as their corresponding operands 


DEVICE, VOLUME and SPACE. 


. Exceptions: 


1. The "ddevice" entry for DDEVICE contains only the 
disk volumes of "device" in DEVICE. 


2. With DSPACE, there is no default value for new files. 


If a user wants to use one of these three operands for a 
file which as yet has no storage space, he must specify all 
three operands. If space has already been allocated for a 
file, only the DSPACE operand need be specified in the FILE 
command. DDEVICE and DVOLUME do not then need to be 
specified. 


If an ISAM file has been created in this vay, it is 
subsequentLy impossible to place data and index blocks on 
one and the same volume. To do this, the file must be 
copied to a second ISAM file whose storage space vas 
aLLocated vithout the use of DDEVICE, DVOLUME and DSPACE. 


It is not possible to divide up an ISAM file of this kind 


on pubLic volumes or on a mixture of private and public 
voLumes. 
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DSPACE=(firstpage,amount,ABS) 


WRCHK=YES 


This operand is accepted for private disks only; it is 
meaningless unless a vsn is specified at the same time in 
the VOLUME operand. 


"ABS" specifies an absolute allocation. If this is the 
first allocation for a file, the value of the secondary 
allocation is set to zero. 


The specification "firstpage" defines the physical block 
(2048 bytes) with which the space allocation is to begin. 
Since only multiples of 3 can ever be requested, the entry 
"firstpage" must contain the values 1, Ma 7: Otley Jo. 
"firstpage" divided by 3 must always Leave a remainder of 1. 


The entry "amount" defines the number of PAM bLocks to bo 
requested. This value must be a multiple of 3. 


An absolute allocation is made only if the whole of the area 
requested can be reserved for the file, i.e. partial 
assignments are not possible. 


In the case of absolute allocation, only one volume can be 
referenced per FILE command. If the user has specified more 
than one vsn in the DVOLUME operand, only the first vsn is 
used. If space is to be allocated on several (n) volumes, 
the FILE command must then be issued n times. 


Note for DDEVICE, DVOLUME and DSPACE: 


In subsequent ISAM versions, an improved buffer management 


Will make the division into data section and file section 
redundant. For reasons of compatibility the DDEVICE, 
DVOLUME and DSPACE operands will still be supported, but 
they will have no effect on processing. 


A read-after-urite check is performed on the data. This 
check refers simply to the checking of the records to 
ensure that the data written is readable; the contents are 
not checked. This method permits recording errors on the 
disk to be detected in good time and to be corrected by 
means of appropriate recovery measures. If the error cannot 
be recovered, a branch is made to the ERRADDR routine 

(via EXLST). 


Notes: 


- A read-after-urite check requires an additional turning 
of the disk, which has an adverse effect on System 
performance. 


- This entry is not recorded in the catalog entry of the 
file. This means that the entry must be specified 
explicitly for any processing of the file. It must be 
valid for the file when it is opened. 


No read-after-vrite check is performed. 
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Example 1: 


/FSTAT M.1 

*  DMS0533 REQUESTED FILE NOT CATALOGED ON PYS V. CMD TERMINATED 
/FILE M.1 
/FSTAT M. 1,ALL 

0000003 :V: $PM211034. M. 1 


1) 


FCBTYPE = NONE VSNTYPE = PUB LASTPG = 0000000 2ND ALLO= 00009 
SHARE = NO ACCESS = WRITE 
ACCESS# = OOO CRDATE = NONE EXDATE = NONE LADATE = NONE 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 ^ BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE 
BLKTYPE = NONE BLKSIZE = 000000 RECFORM = NONE RECSIZE = 00000 
VSN/DEV/EXT = PUBVOS/D3475/001 
EXTONT = 2 4.4 
:V: PUBLIC: 1 FILE... RES? 3, FREE= 3, REL 3 PAGES 
/FSTAT D. DG6G1, TYPE-FGG,GENZYES | ——— —— — ———————————————————————————————— 2) 9 
% DMS0533 REQUESTED FILE NOT CATALOGED ON PYS V. CMD TERMINATED 
/CAT D.DGG1,GEN=5 | 
/FILE D. DGG1 X1)  —————————————————————————————————— 3) 
/FSTAT D. ,TYPE-FGG,GEN-YES 
0000000 :V:$PM211023.D.DGG1 (FGG) 
0000003 :V:$PM211023. D. DGG1 ( *0001) 
:V: PUBLIC: 2 FILES. RES- 3, FREE= 3. REt= 3 PAGES 


1) and 3) As a result of the FILE command, file M.1 and file generation 
D.DGG(*1) are: 


= cataloged 

- given a reservation of 3 PAM blocks (default value) on the 
public disk mounted on device type D3475 with the voLume 
serial number PUBVOS. 


2) If there is as yet no group entry for D.DGG(*1), it must be 
created before the FILE command. 


ExampLe 2: 


The file editor EDT performs standard processing on variabLe-Length records. 
The file Link name for the input/output of SAM files is EDTSAM. 


In order, for example, to process fixed-Length records (in the exampLe the 
record Length is 10 bytes), a FILE command must be issued before the call. 


/FILE M. EDT,LINK-EDTSAM,RECFORM-F ,RECSIZE-10 


/EXEC EDT 
% BLSOSOO PROGRAM EDT, VERSION 160 OF 84-12-03 LOADED. 
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Example 3: 


In FORTRAN programs (also COBOL, RPG2, etc.) file Link names can be 
specified (LINK=). A file name is not assigned to this Link name until a 
FILE command is issued. 


/FILE FOR. AUSGABE,LINK=DSET20 
/EXEC FOR. PROGRAMM 
/RELEASE DSET20 


In this case, the FORTRAN program FOR.PROGRAMM contains the entry "20", i.e. 
the fiLe Link name DSET20. The FILE command connects the five name 

FOR. AUSGABE to this Link name, i.e. a corresponding Task File Table (TFT) 
entry is set up vhich brings about the desired assignment during file 
opening. 


ExampLe 4: 
Space reservation on public volumes (default) 


/FILE Me2,SPACE=S  ——— — — — ——————————————————— 13 
/ΛΕΘΤΑΤ M.2 

0000006 .: V: $PM211034. M. 2 

«υγ: PUBLIC: 1 FILE. RES= 6, FREE= 6, REL= 6 PAGES 
/FILE M. 2,SPACEZ(15) | ——— ——— —————————————————————— 2) 
/FSTAT M.2 

0000021 :V:$PH211034. M. 2 

«ὧν: PUBLIC: 1 FILE. . RES 2l, FREE= 2l, REL= 21 PAGES 
/FILE M. 2, SPACE = (<10) | ——— — A —————————————————— 3) 
/FSTAT M.2 | 

0000009 :V: $PM211034. M. 2 

ty: PUBLIC: 1 FILE. RES= 9, FREE= 9, REL- 9 PAGES 


1) The space request for 5 PAM blocks is rounded up to a multiple of 3, 
with the result that a primary allocation of 6 PAM blocks is made. 


2) An additional 15 PAM bLocks are reserved. 


3) Space is released. Here, too, the entry is rounded up to.a multiple of 3. 


/FILE M. 3, SPACEZ(9,9) | ——— ————— ————————————M—————— 4) 
/FSTAT M. 5,5 
0000009 :V:$PM211034.M. 3 

FCBTYPE = NONE VSNTYPE = PUB LASTPG = 0000000 2ND ALLO- 00009 
tV: PUBLIC: 1 FILE. RES= 9, FREE= 9, REL= 9 PAGES 
/FILE M. 3,SPACEZ(Q,4) -------ης'''''''' 5) 
/FSTAT Μι 5,8 
0000009 :V: $PM211034. M. 3 

FCBTYPE = NONE VSNTYPE - PUB LASTPG = 0000000 2ND ALLO- 00004 
SV: PUBLICO: 1 FILE. RES= 9, FREE= 9, REL= 9 PAGES 


4) Primary allocation and secondary allocation are specified. 


9) Only the secondary allocation is changed. 
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FSTATUS REQUEST CATALOG INFORMATION 


The FSTATUS command is used to request information from the catalog about the 
status of files. The user can request information for one or more individual 
files, for file generations, for file generation groups, for temporary files, 
or for all the files under one user ID. In addition, the information can be 
selected according to file attributes or file and volume type, or be 
restricted to newly opened file generations. : 


Operation Operands 


Pioni pathname 
FSTAT L 1 
prefix 


C,SCETANDARDIJC,CLATALOGI] 9 
| [,TERAITSI]JE,PLASSWORD1] 
C4 LEALL] 
,RLESERVED] 
RLEAD]I 
] 


t saCocESSI=| 
WERITEJ 


πο ο Ὁ Dp» 


C,BCACKUP] = J 


date 
(date,) 2 
C CRCDATE] = 1 


(,date) 
(date,date) 


date 

(date,) 
C,EXCDATEJ= J 

(,date) 

(date,date) 


value 

(value,) 
C,EXTCENTSJ= 1 

(,value) 

(vaLue,vaLue) 
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Operation Operands 


PLAM] 

SLAM] 

ILSAMJ 

NLONE]J 

C,FCBC TYPE] = ] 

PLAnJ 
SCAM] 

( IPOD 
ICSAM] 
NCONEJ 


SIZE 
value 
Γ,ΕΓΕΕΕΙΞΙΖΕΞΙ(ναιυθ,) ] 
(,value) 
© (value,vaLlue) 


CATLALOG]J 
[ ,FROM-z ] 
(vsn,device) 


date 

(date,). 
C,LACDATE] = J 
(,date) 

(date,date) 


target | 
1 


t asm 

(target,type 

RLDPASSJ 

WLRPASSJ 

ECXPASS] 

NLONEJ 

C,PCASS]= J 
RLDPASS]J 


© WECRPASS] 
͵ Ρ5 595. ) 
ECXPASS] 


NLONE1 


YLESJ 
L,SAVE- ] 
NCO] 


YLES]J 
L ,SHLARE1- ] 
NCOJ 


Lem 


FLREEJSIZE 
value 

C,SIZE=}j (value,) J 
(,value) 
(value,vaLlue) 


ELILEJNAH 
[,SORT- 1 
Νίο] 
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Operation Operands 
icd 
] 


tsrare- 
PCLOSE 


PUBCLIC] | 
J 


¢ /SUPCPORTI =| PROL TSC) 
(PUBLLICI,PRDLISCI) 


YLES] 
[,GEN- J 

Ντο). 
[L,TYPE-FGG] 


YLES] 
[,VTOC- ] 
ΝΕΟΙ 


:-catid: [$userid. J [filename] 
"pathname" stands for: guserid. [filename] 
filename 


catid This operand denotes a catalog identifier. If no entry is 
made, the default value assigned to the user ID is assumed. 


Within the operands "catid" and "filename" the following 
symbols are allowed: 


Symbol Meaning 

* This replaces any (also a blank) character 
string. 

/ This replaces any single character. 

«51:52» This replaces a character string situated 
LexicographicaLly between the character strings 9 


"s1" and "52" (both inclusive). Strings "51 

and "52" may also be the blank strings. If 
string "s1" is shorter than string "s2", it 

will be padded with X'QO' to match the Length 

of string "s2". 1f character. string ts2" is 
shorter than character string "si", it will be 
filled with X'FF' to match the size of character 
string "s1". 


«512,55.» This replaces one of the specified character 
strings, which may also be a blank character 
string. Any of the specified alternatives may 
also consist of range "s1:s2" (see above). 


4 This character is allowed only as a symbol at 
the beginning of a file name. It serves to 
negate the next specification, i.e. all files 
that do not satisfy the next name specification 
are Listed. 


3952 UB05-J-Z55-5-7600 


userid 


filename 


prefix 


SC TANDARD] 


CCATALOG] 


FSTATUS 


This operand specifies a user identification. The entry 
$userid designates all files belonging to the user. If the 
user ID of another user is specified, only information 
concerning shareable files (SHARE=YES) is output. 

If the operand is not specified, the user's own user ID 

is assumed. 


This operand specifies the file(s) whose status is to be 
output. This may be a partially or fully qualified file 
name, the name of a file generation or the partially or 
fully qualified name of a file generation group. 


The maximum Length of the file name is 80 characters. 
Temporary files are also taken into account. 


The prefix (special character) specifies that information on 
all the temporary files of this job is to be output. The 
internal name of these files is always output. 


This operand causes the following information to be output 
in addition to the current data on space allocation: 


FCBTYPE Access method used when the file was created. 

VSNTYPE Type of volume on which the file resides (PUB 
for public, PVT for private volumes). 

2ND ALLO Value of the secondary allocation for the file. 

LAST PG Number of the Last page used by this file 
(only for files with standard blocks). 

2nd Line: 

sx identifier of the catalog ("catid") in which the 
files are cataloged. 

FILES Number of files on public volumes (PUBLIC), 
private disks (PRIVATE) and on tape (TAPE). 

RES= Total number of reserved PAM blocks. 

FREE= Number of free (not reserved) PAM blocks. 

REL- Number of PAM bLocks that can be released. This 


is not the same as the number of free bLocks, 
as PAM blocks can only be released in multiples 
of 3 for each file (cf. the FILE command). 


In addition to information on current space allocation, 
this operand outputs the following information defined by 
the CATALOG command. 


SHARE Shareability. 

ACCESS Type of file access (read only or read and 
write). ! 

ACCESS# Number of accesses. 


This count is set to 0 when the file is created 
and incremented by 1 each time the file is 
opened. Once the value 255 is reached, the 
count remains unchanged. 


CRDATE Creation date (YY-MM-DD). 

EXDATE Expiration date (YY-MM-DD). 

LADATE Date of the Last file access (YY-MM-DD). 
RDPASS Read passvord required. 

WRPASS Write password required. 

EXPASS Execute password required. 

VERSION Version number of the original file. 
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BACKUP# 


LARGE 


BACKUP 


DESTROY 


AUDIT 


It is set as follows when the file is opened: 


- In OUTPUT or OUTIN mode it is set to 1. 
- In INOUT or EXTEND mode it is set to the 
value of "BACKUPA" + 1 (where 255 + 1 = 0). 


The number of the Last file version saved. This 
informs the user whether or not the Last version 
of the file has already been saved by the file 
saving system ARCHIVE. 


If BACKUP# = VERSION, the newest version of the 
file has already been saved at Least once. 

If BACKUP# + VERSION, the newest version of the 
file has not yet been saved. 

BACKUP is set to zero if the file is opened 

in OUTPUT or OUTIN mode. 


This attribute specifies vhether the file is 
saved in its entirety during save runs using 
the file saving system ARCHIVE (i.e. LARGE=NO) 
or whether only those PAM blocks are saved 
vhich have been modified since the Last save 
run (i.e. LARGE-YES). 


Save Level when saved with the file saving 
system ARCHIVE. 


Data is destroyed when deleted. 


Monitoring by system exit routines. 


In addition, the current storage allocation, distributed 
over private and public volumes, and the associated 
number of files are Listed. 


For a description of the 2nd Line see STANDARD above. 


TCRALTS] This operand specifies that the following file and volume 

information will be produced: 

BLKTYPE Buffer type (block type) 

BLKSIZE Buffer size (bLock size) 

RECFORM Record format 

RECSIZE Record size 

KEYLEN Key Length for ISAM records 

KEYPOS Position of key for ISAM records 

LOGLEN Length of Logical flag (ISAM only) 

VALLEN Length of value flag (ISAM onty) 

VALPROP Continuation of value flag (ISAM only) 

VSN/DEV/EXT Volume serial number/device type/extents 
* No extent on this volume ὄ 
/nnn Number of extents on this volume 

EXTCNT Total number of extents; 
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maximum number of extents: 319 
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ALL 


PCASSWORD] 


RLESERVEDJ 


ALCCESSJ 


- BCACKUP]J = 


CRLDATEJ 


-RLEADJ 


=W[ RITE] 


=date 


=(date,) 


=(,date) 


FSTATUS 


The following information is issued for file generation 
groups: 


GEN Maximum number of generations allowed 

BASE Base value 

LASTGN Last generation 

FIRSTGN First generation 

DISP Value specified in the DISP operand of the 


CATALOG command. 
For a description of the second Line see STANDARD above. 


This operand requests output of all information concerning 
the operands STANDARD, CATALOG and TRAITS. 


This operand specifies whether the file is passvord- 
protected. The passvords themselves are not output. Users 
who have forgotten their passwords must obtain assistance 
from the system administrator. 


For a description of the 2nd Line see STANDARD above. 


This operand specifies that the total number of reserved 


PAM blocks is to be output, divided up according to whether 
they are on public or on private volumes. 

The storage allocation specified by this operand also 
includes the PAM blocks occupied by the file generation 
groups. 

This operand assumes the entry GEN-YES. 

The operands STANDARD, CATALOG, TRAITS and PASSWORD 

are ignored. 


This operand Lists files for which only read access is 
specified. 


This operand Lists files for which write access is 
specified. | 


If the ACCESS operand is not specified, catalog entry 
selection is not based on specific access methods. 


This operand requests all files with the specified save 
Level. Several save Levels may be specified, in which case 
all the files with any of the named save Levels in the 
catalog entry will be Listed. 


If the BACKUP operand is omitted, catalog entry selection 
is not based on specific save Levels. 


This operand requests all the files with the specified 
creation date. 


This operand requests all the files created from the 
specified date to the current date (inclusive). 


This operand requests all the files with creation dates 
ranging from 19000101 to the date specified (inclusive). 
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=(date,date) 
This operand requests all the files with creation dates 
Lying in the specified range. 


Date entries are specified in the form "YYMMDD" and must 
correspond to exact dates. The specifications 
YCESTERDAYJ, TLODAY] and TOMLORROW] are also accepted. 


If the CRDATE operand is omitted, catalog entry selection 
is not based on specific creation dates. 


EXLDATEJ =date This operand requests all the files with the specified 
expiration date. 


=(date,) This operand requests all the files with expiration dates 
ranging from the specified date to 1999-12-31 (inclusive). 


=(,date) This operand requests all the files with expiration dates 
ranging from 19000101 to the specified date (inclusive). 9 


=(date,date) 
This operand requests all the files with expiration dates 
Lying within the specified range. 


Date entries are made in the form "YYMMDD" and must each 
correspond to an exact date. The entries YLESTERDAY]l, 
TLODAY] and TOMLORROW] are also accepted. 


If the EXDATE operand is omitted, catalog entry selection 
is not based on specific expiration dates. 


Format of date specifications: 


For the selection criteria CRDATE, EXDATE and LADATE the 
date can be specified both as an absolute and as a relative 
value. ; 


Absolute value 
This refers to a specific date in the form YYYY-MM-DD, 
where YYYY is the year, MM the month and DD the day. When 


specifying the year, the century can be omitted, as can 
Leading zeros for the specification of the month and the 9 
daye 


Relative value 

The date can also be specified as the distance in days from 
the current date, "-N" indicating the past, "+N" the 
future. Leading zeros can be omitted, but the signs are 
mandatory. 

A simpLe method of specifying "immediate" dates is provided 
by the predefined terms YLESTERDAY] (specified as -1), 
TLODAY] (specified as +0 or -0), and TOMLORROW] (specified 
as +1). 


3-56 U805-J-Z55-5-7600 


FSTATUS 


EXTCENTS]=value This operand outputs each disk file with exactly the 
| requested number of extents. 


=(vaLlue,) 
This operand outputs all the disk files whose number of 
extents is greater than or equal to the value specified. 


=(,value) 
This operand outputs all the disk files whose number of 
extents is Less than or equal to the value specified. 


=(value,vaLlue) 
This operand outputs all the disk files whose number of 
extents Lies within the range specified. 


For “value” all integers in the following range are 
permissibLe: 


O < value < 65535 


If the EXTENTS operand is omitted, catalog entry selection 
is not based on the number of extents. 


FCBLTYPEJ-PLAM] This operand requests all the files having the specified 
-SLAM] access method. More than one access method can be 
-ILSAM] specified, in which case all the files with one of the 
=NCONE] specified access methods are Listed. 
If the FCBTYPE operand is omitted, catalog entry selection 
is not based on specific access methods. 


FLREEJSIZE-SIZE ALL the disk files for which not all the reserved Lists 
are actually occupied are output. 


=value Each disk file with exactly the requested number of reserved 
but not occupied PAM bLocks is output. 


-z(value,) 
ALL the disk files whose number of reserved but not 
occupied PAM bLocks is greater than or equal to the value 
specified are output. 


=(,vaLlue) 
ALL the disk files whose number of reserved but not 
occupied PAM blocks is Less than or equal to the value 
specified are output. 


-(vaLue,vaLue) 
ALL the disk files whose number of reserved but not 
occupied PAM bLocks Lies vithin the range specified are 
output. | 


For "vaLue" all integers in the following range are 
permitted: 


O S value < 16777215 
If the FREESIZE operand is omitted, catalog entry 


‘selection is not based on the number of PAM blocks which 
are not occupied. 
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FROM=CATCALOG]I 


=(vsn,device) 


LALDATEJ =date 


=(date,) 


=(,date) 


The information on the file(s) is read from the system 
catalog with the specified "catid". If no catalog ID is 
specified, the user's standard catalog ID is assumed. 


The information on the file(s) is read from the directory 
of the private disk with the specified vsn. The device type 
of the disk must be specified, the following entries for 
"device" being possible: D3455, D3465, D3468, D3470, D3475, 
D3480, D348E. 

The operands VOLUME=, SUPPORT= and VTOC are prohibited if 
this operand is specified. 

The "catid" specification is ignored if the FROM operand 

is specified. 


This operand requests all the files with the specified 
Last access date. 


This operand requests all the files which were Last accessed 
between the date specified and the current date (inclusive). 


This operand requests all the files whose Last access date 
Lies between 19000101 and the date specified (inclusive). 


=(date,date) 


PCASSJ=RCDPASS] 
-WLRPASS] 
-ELXPASS] 
-NLONEJ 


LLISTl-target 


This operand requests all the files whose Last access date 
Lies in the specified range. 

Date entries are specified in the form "YYMMDD" and must 
correspond to exact dates. The specifications 

YLESTERDAY1, TLODAY] and TOMLORROW] are also accepted. 

If the LADATE operand is omitted, catalog entry selection 
is not based on specific access dates. 


This operand requests all the files that are protected by 
an appropriate password type. More than one password type 
can be specified. Any five identified by at Least one of 
the password types specified is Listed. 


Meaning of password types: 


RDPASS File is read-protected 

WRPASS File is write-protected 

EXPASS File is execute-protected 

NONE File is not passvord-protected 


If the PASS operand is omitted, catalog entry selection 
is not based on specific passwords. 


The requested information is output in tabLe form to the 
specified output medium. The following specifications may be 
made for "target": 


(SYSLST) System file SYSLST 
(SL) System file SYSLST 
(PRINT) Printer 

(PR) Printer 

Listfive File 
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-(target,type) 
The requested information is output in tabLe form to the 
specified output medium, in which case the output format is 
defined. Possible specifications for "type" are: 


STANDARD TabLe specification (standard) 
STD Table specification (standard) 
FCILENAM] File name only 


Standard output is in the form of an edited List containing 
control characters. 

When the operand LIST=(target,FILE) is used to specify the 
file names, the file names are issued separately, each 
record beginning with a blank (X'40'). 


When LIST is specified, the operands S, T, P, C and R are 

not permitted. 

If the LIST operand is omitted, the requested information 
e is output via SYSOUT (default value). 


SAVE=YCES] This operand Lists all the files whose Last version has 
been changed at Least once with the file saving system 
ARCHIVE; i.e. BACKUP# = VERSION. 


-NLOJ This operand Lists all the files whose current version has 
not yet been saved with the file saving system ARCHIVE; 
i.e. BACKUP# + VERSION. 


If the SAVE operand is omitted, catalog entry selection 
is performed without regard to whether the file has been 
saved or not. 


SHARE=YCES] This operand Lists all the files which can also be accessed 
from other user IDs. 


-NLOJ This operand Lists all the files to which only the owner 
has access. 


If the SHARE operand is not specified, catalog entry 

selection is not based on access authorization. 

However, if the user's own "userid" is not specified, only 
eG shareabLles files for which access authorization has been 

given are selected. 


SIZE=FCREEJSIZE ALL those files are output which contain reserved pages 
that are not occupied. 


-vaLue Each disk file with the requested number of PAM blocks is 
Listed. For values that are not multiples of three the 
preceding or subsequent multiple of three is assumed as 
the vaLue. 


=(vaLlue,) This operand outputs all the disk files whose number of PAM 
blocks is greater than or equal to the specified value. 


=( value) This operand outputs all the disk files whose number of PAM 
blocks is Less than or equal to the specified value. 
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=(value,value) 


SORT=ECLILEJ NAME 


=NCOJ 


STATE=NOCLOS 


=PCLOSE 


SUP[PORT] = 
=PUBCLIC] 
-PRDLISC] 


TYPE-FGG 


3-60 


This operand outputs all the disk files whose number of 
PAM bLocks Lies within the specified range. 


For "vaLue" all integers in the following range are 
permitted: 


O < value < 16777215 


If the SIZE operand is omitted, catalog entry selection 
is not based on the number of PAM blocks alLocated. 


Files are output in alphabetical order (default value). 


Files are output in the order in which they are Listed 
in the catalog. 


This operand requests information concerning currently 
opened output files (and file generations) which vere: 


- opened normally with "OUT" (OPEN mode OUTIN, INOUT 
or OUTPUT) 


- not closed in a previous session 


- not closed in the current session because the job 
was terminated before completion (abnormal job 
termination - "pended indefinitely”). 


This operand requests information on files for which a 
dummy close was performed. 


If this entry is omitted, the catalog entry selection 
is performed vithout regard to whether an output fiLe 
is open or cLosed. 


Catalog entries of files which include an entry for the 
type of volume specified are output. When both types of 
volumes are specified, the catlog entries of files on both 
pubLic and private volumes are Listed. 


Where: 
PUBLIC PubLic volume 
PRDISC Private disk 


If the SUPPORT operand is omitted, catalog entry selection 
is not based on specific volume types. 


This operand specifies that only information concerning 
file generation groups is to be output. 


If this entry is omitted, the selection of catalog entries 
is unrestricted. 
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GEN=YCES] 


ΞΟ 


VOLLUMEJ -vsn 


VTOC-YLES] 


© Notes: 


FSTATUS 


This operand requests information on all generations of a 
file generation group and is ignored if "filename" is not 
the name of a file generation group. 


No information concerning file generations is output 
(default value). 


Operands Types of catalog entry which may be output: 


TYPE | GEN File generation File generations Files 
-FGG|-YES deus 


This operand outputs all file names and status information 
for files which have an entry in the catalog for the 
specified voLume. 


This operand outputs the VTOC catalog entries (from the F1 
Label of a private disk) on the basis of the Last current 
status in the entire computer network. 

If the specified file no Longer resides on the private 
volume specified in the catalog entry, the catalog entry 
is deleted. 

This entry causes all other keyword operands to be ignored. 


This operand outputs the TSOS catalog entries - on the 
basis of the Last current status in an individual co-~user. 
(Co-user: CPU for which a random access device was defined 
as shareable. ) 


=- Auxiliary function of the FSTATUS command: 


In interactive mode only; this command is ineffective in batch mode. 


Operation 
puts 
FSTAT 


HELP 


Operands 


,HLELP]J 


The syntax of the FSTATUS command is output. 


If other operands are specified at the same time, they are 
ineffective. 
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If the FSTATUS command is entered without operands, information on 
storage reservation and names of files under the user's own user ID (in 
alphabetical order) are output. 


Up to five positional operands can be specified. 


Any number of the operands CATALOG, STANDARD, TRAITS, PASSWORD and ALL 
can be specified in any order. 


In interactive mode, the BREAK function can be used to interrupt the 
output of FSTATUS information. 


If the operand VTOC=YES is specified, the volume must be assigned for 
the executing processor. 


If VTOC=YES is entered, the other specified key operands are ignored. 


The VTOC operand is ignored unless the file concerned is a private random 
access file. It is also rejected if the file name is only partially 
qualified or if the operand "GEN-YES" vas specified. 


If a TSOSCAT entry exists, but no corresponding VTOC entry, the TSOSCAT 
entry is deleted, provided VTOC=YES has been specified. 


Specification of VTOC=YES causes the VTOC entry for the private volume to 
be read; this replaces the corresponding TSOSCAT entry. This action 
restores consistency between the VTOC and TSOS catalog entries, should 
this have been Lost due to a file having been updated by another co-user. 


Network catalog management (see also the "MSCF MuLtiprocessor system" manual) 


Any "catid" or "userid" can be specified. A distinction is drawn between 
the following different cases: 


Without operands: 
ALL file entries from the user's own catalog belonging to the job-specific 
standard user ID are output. 


There is a catalog ID, but no user ID: 

ALL file entries from the catalog with the specified catalog ID belonging 
to the job-specific standard user ID are output. In this case, the 
command has the following format: 

FSTAT :catid: 


Only the user ID is specified: 
The file entries from the standard catalog belonging to the specified 
user ID are output. 
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ExampLes: 
ALL files under the user's own user ID are output in alphabetical order: 


/FSTAT 

0000030 :V: $PM211023. BEISPIEL 

0000846 :V:$PM211023. DVS. BAND 

0000006 :V:$PMN211023. DYS. KORR 

0000012 :V: $PM211023. KOM. S-R-A 

0000006 :V:$PM211023. PRI 

0000009 :V: $PM211023. SCR. KOM 

0000009 :V: $PM211023. TEST 

σεν PUBLIC: 7 FILES. RES- 918, FREE= 35, REL= 30 PAGES 


ALL shareable files under the user ID $PM211 are output: 


/FSTAT $PM211. 
0000003 :V: $PM211. HELD. LADMOD 
e 0000003 :V: $PM211. NEU. LINK. MSGID. PROG 
0000015 :V: $PM211. NEU. LMS. PROG. MAKROS 
0000003 :V: $PM211. NEU. ΟΚ 
0000003 :V: $PM211. ZE. ANSCHR 
0000003 :V: $PM211. ZE. DR. INFO 
0000114 :V:$PM211. ZELL. NDFILE 
υγ: PUBLIC: 7 FILES. RES= 144, FREE= 9, REL= 3 PAGES 


In the case of files on private disk, an asterisk ("*") appears before the 
file name. 


/FSTAT PRIVAT,ALL 
0000087*: V: $PM211034. PRIVAT 


FCBTYPE = ISAM VSNTYPE = PVT LASTPG = 0000086 2ND ALLO= 00009 
SHARE = NO ACCESS = WRITE 
ACCESS# = 001 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = 85-03-20 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 001 BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE : 
BLKTYPE = STD BLKSIZE = 002048 RECFORM = (V,N) RECSIZE = 00000 
KEYLEN = 008 KEYPOS = 00005 
VSN/DEV/EXT = CO016M/D3468/002 
6 EXTCNT = 2 
:V: PRIVATE: 1 FILE. RES= 87, FREE= 1, REL= O PAGES 


ALL files whose names begin with DVS. are output: 


/FSTAT DVS. 

0000066 :V:$PM211034. DVS. BEISP. 1 

0000006 :V:$PM211034. DVS. PL. BILB 

0001074 :V:$PM211034. DVS. PLATTE 

0000006 :V: $PM211034. DVS. TABELLE. 2-2 

00000086 :V:$PMN211034. DVS. VERTEILER 

ἐγ: PUSLIC: 5 FILES. RES= 1158, FREE= 7, REL= . 0 PAGES 


The number of PAM bLocks used is output: 


./FSTAT ,R 
:V: PUBLIC: 45 FILES. RES- 1746, FREE- 178, REL- 135 PAGES 
:V: PRIVATE: 5 FILES. RES- 1248, FREE- 34, REL- 30 PAGES 
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The number of PAM blocks used by all pubsets under the user ID (in this case 


V and Z) is output. 


The specifications in the totals Line refer to the two pubsets. 


FSTAT :*:,R 


(Nec PUBLIC: 45 FILES. RES= 1746, FREE- 
Vs. Pee eet 5 FILES. RES= 1248, FREE- 
cZ: FORLAG: 19 FILES. RES= 117, FREE= 
SUM PUBLIC: 64 FILES. RES= 1863, FREE= 
SUM PRIVATE: 5 FILES. RES= 1248, FREE- 


Specific information is requested for selected files: 


/FSTAT DATET,ALL 
0000087 :V: SP1211034. DATEI 


FCBTYPE - ISAM VSNTYPE - PUB LASTPG 
SHARE - YES ACCESS = WRITE 
ACCESS# = 018 CRDATE = 85-03-19 EXDATE 
RDPASS = YES WRPASS = YES EXPASS 
VERSION = 001. BACKUP# = O01 LARGE 
DESTROY = NO AUDIT = NONE 
BLKTYPE = STD BLKSIZE = 002048 RECFORM 
KEYLEN = 008 KEYPOS = 00005 
VSN/DEV/EXT = PUBV05/D3475/002 
EXTCNT = Kol 
VI "τοι 1 FILE. RES= 87, FREE= 
/FSTAT ASS. PRO, STANDARD 
0000003 :V: SPH211034. ASS. PRO 
. FCBTYPE = ISAM VSNTYPE - PUB LASTPG 
:V: "PUBLIC: 1 FILE. RES= 3, FREE= 
/FSTAT ASS. PRO,CATALOG 
0000003 :V: $PM211034. ASS. PRO 
SHARE = NO ACCESS = WRITE 
ACCESS# = 022 CRDATE = 85-02-26 EXDATE 
RDPASS = NONE WRPASS = NONE EXPASS 
VERSION = OO1 BACKUP# = 001 LARGE 
DESTROY = NO AUDIT = NONE 
"γι Æ PUBLIC? 1 FILE. RES= 3, FREE= 
/FSTAT BEISPIEL, TRAITS 
0000030 :V:$PM211034. BEISPIEL 
BLKTYPE = STD BLKSIZE = 002048 RECFORM 
VSN/DEV/EXT = PUBV11/D3475/001 
EXTCNT = 1. : 
«υγ: (PUBLIC: 1 FILE. RES= 30, FREE= 
/FSTAT DATEI,PASSWORD 
0000087 :V: SPM211034. DATEI 
RDPASS = YES WRPASS = YES EXPASS 
«γα PUBLIC: 1 FILE.  RES- - 87, FREE= 


The names of opened output files are requested: 


/FSTAT ,STATE=NOCLOS 
0000030 :V:$PM211034. BEISPIEL 
οὐ». PUBLIC: 1 FILE. RES= 30, FREE= 


0000086 


85-03-19 


YES 


1, 


0000002 
1, 


REL= 135 PAGES 
REL= 30 PAGES 
REL= 3 PAGES 
REL= 138 PAGES 
REL= 30 PAGES 
2ND ALLO- 00012 
LADATE = 85-03-20 
BACKUP =A 
RECSIZE = 00000 
REL= O PAGES 
2ND ALLO- 00009 
REL= O PAGES 


85-02-26 LADATE = 


NONE 
NO 


1, 


(V,N) 


30, 


YES 
1, 


30, 


85-03-08 
BACKUP =A 
REL= O PAGES 
RECSIZE = 00000 
REL= 30 PAGES 
REL= O PAGES 
REL- 30 PAGES 
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The names of all file generation groups are output: 


/FSTAT. TYPE=FGG 

ΟΟΟΟΟΟΟ :V: $PM211034.C.DGG (FGG) 

J000000 :V: $PM211034.0GG1 (FGG) 

0000000 :V: $PM211034.DGG2 (FGG) 

«υγ: PUBLIC: 3 FILES. RES= O, FREE= O, REL= O PAGES 


The names of all file generation groups, including file generations, are 
output: 


/FSTAT TYPE=FGG,GEN=YES 
0000000 :V:$PM211023.DGG1 (FGG) 
0000006 :Y: $PM211023. DGG1(*0001) 
0000009 :V:$PM211023. DGG1(*0002) 
0000012 :V:$PM211023. DGG1(*0003) 
0000012 :V:$PM211023. DGG1(*0004) 
0000006 :V:$PM211023. DGG1(*0005) 
:V: PUBLIC: 6 FILES. RES= 45, FREE- 4, REL- ο PAGES 


ALL files, including file generations under the user's own user ID, are 
output: 


/FSTAT ,GEN=YES 
0000030 :V: $PM211023. BEISPIEL 
0000000 :V:$PM211023.DGG1 (FGG) 
0000006 :V: $PM211023. DGG1( *0001) 
0000009 :V: $PM211023. DGG1( *0002) 
0000012 .: V: $PM211023. DGG1( *0003) 
0000012 :V:$PM211023. DGG1( *0004) 
0000006 :V: $PM211023. DGG1( *0005) 
0000846 :V: $PM211023. DVS. BAND 
O000006 :V: $P4211023. DVS. KORR 
0000012 :V:$PM211023. KOM. S-R-A 
0000006 :V: SP1211023. PRI | 
0000009 :V: $PM211023. SCR. KOM 
0000009 :V: $PM211023. TEST 

VI : PUBLIC: 13 FILES. RES= 963, FREE= 39, REL= 30 PAGES 


ALL files under the user ID are output (corresponds to FSTAT without 
operands). : 


/FSTAT * 

0000030 :V:$PM211023. BEISPIEL 

0000000 :V:$PM211023.DGG1 (FGG) 

0000846 :V: $PM211023. DVS. BAND 

0000006 :V:$PM211023. DVS. KORR 

0000012 :V: $PM211023. KOM. S-R-A 

0000006 :V:$PM211023. PRI 

0000009 :V: $PM211023. SCR. KOM 

0000009 :V: $PM211023. TEST | 

: V: PUBLIC: 8 FILES. RES= 918, FREE= 35, REL= 30 PAGES 


ALL files whose names consist of only three characters are Listed. 


/FSTAT /// 

0000003 :V: $PM211034. ASS 

0000030 :V: $PM211034. DAT 

0000003 :V: $PM211034.M. 1 

0000009 :V:$PM211034.M. 2 

0000009 :V: $PM211034. M. 3 

:V: PUBLIC: o FILES. RES= 54, FREE= 28, REL= 24 PAGES 
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ALL files with names beginning with the Letter D or a Letter in the range 
from X to Z (inclusive) are Listed. 


/FSTAT <D,X:Z>* 

0000030 :V:$PM211034. DAT 

0000087 :V:$PM211034. DATEL 

0000087 :V:$PN211034. DATEL. KOPIE 
0000000 :V:$PM211034.DGG1 (FGG) 
0000000 :V: $PM211034.DGG2 (FGG) 
0000003 :V: $PM211034. DO. BEISPIEL 
0000066 :V: $PM211034. DVS. BEISP. 1 
0000006 :V: $PM211034. DVS. PL. BILB 
0001074 :V:$PM211034.DVS. PLATTE 
0000006 :V: $PM211034. DVS. TABELLE. 2-2 
0000006 :V: $PM211034. DVS. VERTEILER 
0000003 :V:$PM211034.ZE. ASS 

sV: Pee 12 FILES. RES= 1368, FREE= 16, REL= 3 PAGES 


ALL those files are Listed whose names are not 4 characters in Length and ὠ 
which are read-protected/write-protected. 


/ΛΕΘΤΑΤ -////,PASS=(R,W) 
0000087 :V: $PM1211034. DATEI 
0000087 :V: SP1211034. DATEI. KOPIE 


ALL files on private disk C0016M are output to SYSLST in table form. 
/FSTAT ,VOLUME-COO16M,L-z(SL) 


FILE STATUS ., VOLUME=C0016M,L=(SL) 07 


FILENAME PAM FREE SECOND PASS-|BKL| #EXT VOLUME 
PAGES PAGES ALLOC. WORDS 


- $PM211034. DO NO C, 
COWPGM 


: $PM211034. FROH i 

: $PM211034. PRIVAT CO016M 
: $PM211034. SAVE COO16M 
> $PM211034. SYSTEM c0016M 


* + + + + 
[ee 


PRIVATE SPACE: 5 FILES 


In the PAM PAGES coLumn, the entire memory space occupied by the volumes 
in use is output. If a file reserves space on more than one volume, the 
vsn is preceded by an asterisk ("*") in the VOLUME coLumn. 
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The temporary file SWORK is output ("#" is the symbol for temporary file). 
The file name is specified via the internal file name S. TMP.nnnn. file, 
where "nnnn" stands for the tsn. 


/FSTAT #WORK,ALL 
0000087 :Y: $PM211034. S. TMP. 8166. WORK | 
0000086 2ND ALLO- 00012 . 


FCBTYPE = ISAM VSNTYPE = PUB LASTPG = 
SHARE = NO ACCESS = WRITE 
ACCESS# = 001 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = 85-03-20 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 001 BACKUP# = 000 LARGE = NO BACKUP ΞΕ 
DESTROY = NO AUDIT = NONE 
BLKTYPE = STD BLKSIZE = 002048 RECFORM = (V,N) RECSIZE = 00000 
KEYLEN = 008 KEYPOS = 00005 
VSN/DEV/EXT = PUBVOS/D3475/001 
EXTCNT = 1 
:V: PUBLIC: 1 FILE. RES= 87, FREE= 1, REL= O PAGES 


e ALL temporary files are output (temporary-file symbol = "f/"). The temporary 
files are output using the file name S. TMP. nnnn. file (where "nnnn" stands 
for the tsn). 


/|FSTAT # 

0000087 :V:$PM211034. S. TMP. 8166. TEIL 

0000087 :V: $PM211034. S. TMP. 8166. TEMP 

0000087 :V:$PM211034. S. TMP. 8166. WORK © 

sV?  PUBLICI 3 FILES. RES- 261, FREE- 3, REL= 0 PAGES 
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HOLD HOLD TFT ENTRY 


The HOLD command is used to place an entry in the Task File Table (TFT) in 
the HOLD status. This serves to defer a subsequent RELEASE command (or REL 
macro) for this TFT entry until a DROP command with the relevant file 

Link name is issued. 


Operation Operands 
HOLD [Link] 
Link This operand specifies the file Link name of a TFT entry to 


Example 1: 
/FILE LINK=X,ece 
/HOLD X 


/RELEASE X 


/DROP X 


ExampLe 2: 


/HOLD Y 


/FILE LINKzY,... 


/DROP Y 


/RELEASE Y 


be placed in the HOLD status. If no file with this name 
existed previously, a new TFT entry is created for this 
Link name (max. 8 bytes). Further entries can be made in 
this TFT entry by means of a subsequent FILE command. If 
"Link" is not specified, the first TFT entry with the Link 
name Ο cuss. is processed. 


An entry vith the name X is created in the TFT. 
The HOLD status indicator is set for TFT entry X. 


The entry X is not deLeted, as it is in the HOLD status. 
However, the command (or REL macro) sets the RELEASE 
indicator in the TFT entry X. 

Only noy does the RELEASE command (or REL macro) take 
effect, the TFT entry X being deleted, and any associated 
private devices released. 


A TFT entry vith the name Y is created, and its HOLD 
status indicator set. 


This command uses the existing TFT entry Y, and makes 
entries in it. 


The HOLD status for entry Y is canceled. As no RELEASE 
command has been issued, no operation is performed. 


The entry Y is no Longer subject to HOLD. 


The RELEASE command thus has the immediate effect of 


deLeting entry Y. 
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Example 3: 
/FILE LINK=A 
/HOLD A 
/CHANGE A,B The name of TFT entry A is changed to B, but everything 
else in the TFT entry remains unchanged, e.g. entry B is 
now subject to the HOLD status. 
/DROP A This command generates an error message as there is 
no Longer an entry with this Link name. 
/RELEASE B The RELEASE indicator is set in TFT entry B, but 
the command is not yet executed as HOLD is in force. 
/DROP B RELEASE becomes effective, i.e. entry B (previously 


entry A) is deleted. 
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IMPORT 


CREATE CATALOG ENTRY FOR PRIVATE FILES 


This command catalogs files contained on a private disk. In so doing, it 
transfers the entries from the disk's F1 Label to the system catalog 
(voLume import). 


Only those files can be cataloged which vere set up on the private disk 
under the same user ID as that under which the calling task is executed. 


This command is particularly suited for the rapid introduction of multiple 
files from a private disk into the system. 


When importing file generation groups whose gener 
different disks, certain rules must be observed; 
notes at the end of the format description. 


ations are Located on 
these are Listed in the 


A function vith the opposite effect to that of the IMPORT command is 
contained in the ERASE command: operand VOLUME=vsn (volume export). 


Operation 


IMPORT 


Operands 


Cpathname,J] VOLUME=vsn,DEVICE=device 


YES 
[ ,REPLACE-z1ABS[1 
NO 


L3 
NO 
ONLY 


C,LIST= 1 
YES SYSLST 
(1NO [,]SYSOUT|) 
ONLYJ (BOTH 


a 
L,GEN- 1 
ΝΟ 


[,PVSID-catidl 


"pathname" stands for: [$userid.]filename 


userid 


filename 


VOLUME=vsn 


3-70 


This operand denotes the user ID 


associated with the file. 


If no entry is made, the user's own user ID is assumed. 
Only the user's own user ID is permitted. 


This operand specifies a fully or partially qualified file 
name or the name of a file generation group. If this 
operand is omitted, the DMS catalogs all the files 


belonging to the calling user. 


This operand specifies the volume serial number of the disk 


(6 characters). 
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DEVICE=device The type of device on which the private disk is to be 
mounted, e.g. D3465 (see also the FILE command, operand 
DEVICE=). 

REPLACE=YES Entries from the F1 Label replace entries with the 


same file name in the system catalog. 
The following situations may occur: 


1. The file whose catalog entry already exists in the 
system catalog is Located on public volumes. If 
permitted by the protection attributes of the file, 
the file is deleted. Otherwise nothing happens. 


2» The file whose catalog entry already exists in the 
system catalog is Located on private disks, but does 
not begin on the disk specified in the IMPORT command. 
If permitted by the protection attributes of the file, 
the catalog entry for the file is deleted (ERASE 

© CATALOG). Otherwise nothing happens. 


3j. The file whose catalog entry already exists in the 
system catalog is Located on private disks and begins 
on the disk specified in the IMPORT command. In this 
case nothing happens. The DMS regards the entry in the 
system catalog as a valid description of the five to be 
imported. 


-ABS Entries from the F1 Label replace entries with the 
same file name in the system cataLog, provided that the 
catalog entries have the same vsn as the disk to be 
imported. 


Three different types of situations can occur: 
1. AS with REPLACE=YES 
2e As with REPLACE=NO 


3j. The catalog entry of the file which is to be imported 
already exists in the system catalog. The file is on 
private disk and begins on the disk which was specified 
e in the IMPORT command. In this case the catalog entry 
is deleted and repLaced by the current entry (return 
code 8). 
If this is not possible due to a file Lock, nothing 
happens, since an import is in this case unnecessary 
(return code 9). 


ΞΝΟ The DMS creates entries in the system catalog only for 
those files which are not yet cataloged. 
LIST=YES This operand causes or suppresses output of a List of 
=NO return information concerning the processing of files. 
=ONLY This operand outputs only a List of files Located on the 


private disk; no import operation is performed. The con- 
tents of the List depend on the operand "filename"; 
special attention should be paid to the following: 


- The information supplied for each file explains how 


these files would have been processed if they had 
been imported into the system. 
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| 


SYSOUT 


BOTH 


sa 


If an entry for a file on the private disk already 


exists in the system catalog, the DMS does not check the 
protection attributes for this file. Should the user 
wish to import the file at some Later time, and if it is 
necessary to delete the previously cataloged file in 


order to to this, 


the user himself must ensure that this 


file can be deleted (ACCESS=WRITE, retention period 
expired, passwords specified). 


These keywords denote the symbolic system file to which 
the List is to be output (SYSOUT - terminal; SYSLST - 


printer; 


BOTH - both terminal and printer). 


In the SYSOUT Listing, the information appears only in the 
form of a code, while the SYSLST Listing outputs the 
corresponding message text. 


The following messages can be output: 


Code on 


SYSOUT 


Ό 
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FILE DID NOT EXIST 
FILE HAS BEEN ERASED 
FILE EXISTS AND 
REPLACE=NO 

FILE IS PROTECTED 


(ERASE ERROR or 
FILE IS IN USE) 


ERROR DURING $RDCT 
(IN CATALOG) 


FILE ALREADY 
ON PRIVATE 


$SCAN ERROR (ON VTOC) 


NOT ALLOWED TO RE- 
CATALOG A GENERATION 


C. E. HAS BEEN 
REPLACED 


FILE IS IN USE 


Message on SYSLST Meaning 


Processing successful. No file with this 
name existed previously. 


A file of the same name already existed 
and has been overwritten. 


A file of the same name already existed 
and has not been overwritten. 


A file of the same name already exists 
and couLd not be erased because of 
active protection functions (ACCESS- 
READ, WRPASS=, etc.), or the file to be 
imported is currently being processed 
(FILE IS IN USED. 


UnrecoverabLe error (CATALOG 
MANAGEMENT). 


The file is already cataloged as a 
foreign file on a private disk and 
REPLACE=ABS is not specified. 
Error in command processing. 


Import of a file generation is not 
permissible. 


The catalog entry for the disk already 
existed and has been overwritten. 


The catalog entry for the disk already 
exists and the file is Locked. 
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GEN=YES This operand imports for a file generation group the group 
entry and all the generations that begin on the private 
disk. If the private disk contains only generations of a 
file generation group but not the group entry, then these 
generations will be cataloged only if the group entry is 
already cataloged. 


=NO This operand imports only the group entry of a file 
generation group. 


PVSID=catid This operand specifies the catalog which is to contain the 
catalog entries. 
If this operand is not specified, the standard catalog ID 
of the user is assumed. 


Notes: 


The functions of the IMPORT command and the ERASE CATALOG, VOLUME=vsn 
command are not exact opposites: 


When a volume is exported, the DMS deletes the catalog entries of all the 
files occupying space on this volume. 


If the same volume is imported again, the DMS creates catalog entries only 
for those files that begin on this volume (i.e. files that received space on 
this disk in the primary allocation). 


When importing or exporting private disks on which file generation groups 
are Located, the following points should be borne in mind: 


1. An IMPORT command catalogs. only those generations whose group entry is 
contained either on the disk specified or in the system cataLog. 


For a file generation group that is distributed over several disks and 
is not yet cataloged, this has the following effect: 


If the disk that does not contain the group entry is imported first, 
followed by the disk with the group entry, the catalog entries for the 
generations contained on the first disk will be missing. 

This can be remedied by issuing either a new IMPORT command for each 
volume affected, or a FILE command (operand STATE=FOREIGN) for each 
uncataLoged generation. 
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Example: 


Two file generations are distributed over three private disks, as 
follows: 


(GRP stands for group entry) 9 


The generations and group entries named are not contained in the system 
catalog. 


The following command sequence is issued: 


/IMPORT VOLUME=DSK001,DEVICE=D3465 
/IMPORT VOLUME=DSKO002,DEVICE=D3465 
/IMPORT VOLUME=DSKO003,DEVICE=D3465 


After these commands have been executed, the following files and group 
entries are cataloged: 


FGG1GRP FGG2GRP 
FGG1(*1) FGG2(*1) 
FGG1(*2) FGG2(*3) 
FGG1(*3) 


(It should be noted that there is no sequence of commands which would 
have cataloged all the generations.) 


Generation FGG2(*2) may subsequently be imported, e.g. with a FILE 23 
command. 


2. If a private disk contains only individual generations of a file 
generation group, but not the group entry, gaps may occur in the five 
generation group when this volume is exported. 
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Example: 


One file generation group is distributed over two private disks as 
follows: 3 


e (GRP stands for group entry) 
The command 
/ERASE CATALOG, VOLUME=DSKO002 


deletes generation 2 from the system catalog, while generations 1 and 3 
remain cataloged as before. This means that there is a gap in the file 


generation group. 
However, this situation affects only the catalog entries; on the disks 


the file generation group is complete. 


Further examples: 


- /IMPORT ,VOLUME=G8002M,DEVICE=D3468,LIST=( YES,SYSOUT) 


O SKRZ. MAN. KDO 
O SKRZ. MAN. MK 
O SKRZ. MAN. MKS 


ALL files under the user ID $KRZ that are Located on the private disk are 
C imported, as the return information output confirms (code=0). 


- /IMPORT ΜΑΝ. MAKRO, VOLUME=G8002M,DEVICE=D3468,LIST=( YES,BOTH) 
O SKRZ. MAN. MAKRO 


The IMPORT command imports the file MAN.MAKRO. In addition to output to 
SYSOUT, there appears on SYSLST the corresponding return information for 
code 0: 


κ κ κ RAP OORT 0 WT e U-T Lo LS. * * * 14:39:19 02/05/83 
IMPORT MAN. MAKRO , VOLUME-ZG8002M,DEVICE-D3468,LIST-(YES,BOTH) 


OLD USER-ID CODE NEW USER-ID CODE FILE NAME 
FILE DID NOT EXIST SKRZ. MAN. MAKRO 
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- The file DUPLIKAT under the user ID $PM211023 is Located on a private disk 
and is to be imported. However, a file with the same name already exists 
under this user ID on a public volume: 


/FSTAT DUPLIKAT 
0000003 :V: $PM211023. DUPLIKAT 
ΣΥ: PUBLIC: 1 FILE. RES= 3, FREE= 1, REL= 0, PAGES 


/IMPORT DUPLIKAT,VOLUME=G8002M,DEVICE=D3468,LIST=( YES,BOTH) 
2 :V: SPM211023. DUPLIKAT 


* * κ a1 P 8 RT OUTPUT L o4 9 I * * * 14:41:10 02/05/83 
IMPORT DUPLIKAT, VOLUME=G8002M,DEVICE=D3468,LIST=( YES,BOTH) 
OLD USER-ID CODE NEW USER-ID CODE FILE NAME 
FILE EXISTS/REPLACE=NO : V: $PM211023. DUPLIKAT 


- The file is not imported, as the SYSOUT and SYSLST Listings show: 


/IMPORT DUPLIKAT,VOLUME=G8002M,DEVICE=D3468,LIST=( YES,BOTH) ,REPLACE=YES 
1 :V:$PMN211023. DUPLIKAT 


* * * Σ:Η.Ρ “ΜῈ ον ου boh ee * * * 14:45:04 02/05/83 
IMPORT DUPLIKAT,VOLUME-ZG8002M,DEVICEZD34658,LIST-(YES,BOTH) ,REPLACE=YES 
OLD USER-ID CODE NEW USER-ID CODE FILE NAME 
FILE HAS BEEN ERASED : V: $PM211023. DUPLIKAT 


- The following SYSOUT Listing names all the files contained on private 
disk under the user ID ΦΚΗΖ. No file import takes place since LIST=ONLY 
was specified. Here the user can ascertain from the codes what would have 
happened in the event of an import: 


/IMPORT ,VOLUME=G8002M,DEVICE=D3468,LIST=(ONLY,SYSOUT) 


2 SKRZ.MAN. KDO 
O SKRZ. MAN. KOM 
2 SKRZ.MAN. MAK 
O SKRZ. MAN. MKR 


The files MAN.KDO and MAN.MAK are imported only if the operand 
REPLACE=YES is specified and if the protection attributes for the 
Like-named files permit it (cf. previous example). 

The other two files can be imported without the necessity for additional 
entries in the IMPORT command which differ from the default values. 
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- 7 file generations (*1 through *7), whose group entry no Longer exists 
(in the catalog and in the F1 Label), are Located on private disk. The 
generations (*2) and (*3) are to be imported. 


/CAT C.DGG,GEN=5,FIRST=2,BASE=3,DEVICE=0D3468, VOLUME=C0016M 3 
/FSTAT C.DGG,GEN=YES,ALL 
0000000*: V: $PM211023. C. DGG (FGG) 
SHARE = NO ACCESS = WRITE 
ACCESS# = 000 CRDATE = 85-03-20 EXDATE = 85-03-20 LADATE = NONE 
RDPASS = NONE WRPASS = NONE EXPASS = NONE 
VERSION = 000 BACKUP# = 000 LARGE = NO BACKUP =A 
DESTROY = NO AUDIT = NONE 
GEN = 00005 BASE = 00003 LASTGN = 00003 FIRSTGN = 00002 
DISP = CYCLE 
VSN/DEV/EXT = CO016M/D3468 
:V: PRIVATE: 1 FILE. RES= O, FREE= ο, REL= 0 PAGES 
/IMPORT ,VOLUME-COO16M,DEVICE-D3468,GEN-YES 
OLD USER-ID CODE NEW USER-ID CODE FILE NAME 
6 FILE EXISTS/REPLACE=NO : V: $PM211023. C. DGG 
FILE EXISTS/REPLACE=NO : V: $PM211023. DUPLIKAT 
/FSTAT C. DGG, GEN-YES 
O000000*: V: $PM211023. C. DGG (FGG) 
0O000003*: V: $PM211023.C.DGG (*0002) 
O000003*: V: $SPM211023. C. DGG (*0003) 
ΣΥ: PRIVATE: 3 FILE. RES- . 6, FREE= 2, REL= O PAGES 


The group entry must be newly created with the CATALOG command for file 
generations without a group entry which are to be imported: 

C.DGG(*2) is the oldest generation to be imported (FIRST=2). 

C.DGG(*3) is the newest generation to be imported (BASE=3). 

The generation number (*3) is also the base value to which all the 
relative generation numbers relate. If the BASE operand is not specified, 
the system imports for BASE the value of the first operand; i.e. only 

one generation is imported (see also the CAT command, operand BASE). 
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PASSWORD = SPECIFY PASSWORD 


The PASSWORD command provides a task with passwords for file opening or for 
access to the catalog entry. For this purpose, a List of passwords (password 
table) is created which can be extended or reduced in stages, or also 
deleted, by means of subsequent PASSWORD commands. 


This password table is searched during processing of the CATALOG, FILE and 
ERASE commands, and also upon file opening, if a password is needed for file 
access and this password is not contained in the File Control Block of the 
program. If the required passvord is found in the table, access is 
permitted. 


At the end of the job the passvord table is deleted. 


Operation Operands 
passvord 

PASSWORD C JL,RELZYLES1J 
(passvord,...) 


passvord This operand specifies a passvord of up to 4 bytes in 
Length; it is represented as follows: 


C'x' "x" consists of 1 to 4 alphanumeric characters and 
special characters; 

X'n' "n" consists of 1 to 8 hexadecimal digits; 

d "d" is a decimal integer consisting of 1 to 8 digits, 
whose value is converted to a binary value. 


A password with the value X'QOO00000' is ignored. Up to 
63 passwords can be specified in one PASSWORD command. 


REL=YCES] This operand specifies that the passwords defined in the 
PASSWORD command are to be deleted from the job's password 
table, so that full password protection is again 
established. 


If no password is specified in congunction with the REL 
operand, the job's entire password table is deleted. 


Notes: 
- The following applies to the use of passwords: 


If both a write password and a read password have been specified for a 
file, the write password assumes the function of both passwords, i.e. if 
the write password is entered, the user can both read and write to the 
file. 


If only a read password has been specified for a file, this must be 
entered for reading and/or writing. An existing read password must be 
entered when modifying the write password. 


If both a read password and an execute password have been specified for 


a file, the read password assumes the function of the execute password, 
i.e. entering the read password allows both reading and execution. 
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- The protection afforded by passwords can be enhanced by means of the 
internal encryption (encoding) of these passwords by the system In 
memory dumps, for example, the passwords appear in coded form only. 
Password encryption is specified at system generation (PARAM ENCRYPT,Y). 


- In addition, the protection afforded by passwords can be further enhanced 
by Limiting the permissible number of invalid entry attempts. 


Remote file access (see also the "RFA" manual) 


e The PASSWORD command is passed on automatically to all RFA partner tasks 
by the requesting job. 


e The passwords are not encrypted before transmission to the remote 
processor. Encryption takes place immediately afterwards, provided the 
computer uses password encryption. 


Example: 
In interactive mode, input includes the following commands: 
/LOGON ... 


/PASSWORD X'51EF* --------------ςς '''''''''.''''''.--.ύϱ1) 
/CAT M. NEU, STATE-U,RDPASS-C' OR* 02) 
/PRINT Me NEU 
X SCPO860 FILE PROTECTED BY A READ PASSWORD. PRINT REQUEST REJECTED FOR 

: V: $PM211023. M. NEU. 
/COPY M.NEU,M. NEU. KOPIE 
X  DMSOSF3 REQUIRED PASSWORD IS NOT IN PASSWORD TABLE. COMMAND TERMINATED 
/PASSWORD C'OR* | ————— ———————— ——————————————————————————————— Q3) 
/COPY M. NEU,M. NEU. KOPIE 
/PASSWORD RELZY | ———————————————— ——— — ———————————————————— ο) 
JER M. NEU 
* DMSO801 ERASE ERROR ON FILE :V:$PM211023. M. NEU | 
Χ  DMSOSBF REQUIRED PASSWORD IS NOT IN PASSWORD TABLE. COMMAND TERMINATED 
JER M. NEU. KOPIE |. —————————————— —————————————————————————— Q5) 
/FSTAT M. NEU 
0000006 :V:$PM211023. M. NEU 
:V: PUBLIC: 1 FILE. RES= '6, FREE= 1, REL= Ὁ PAGES 


- /LOGOFF 


01) The first PASSWORD command in this job serves to set up its passvord 
| table and enter the password X'51EF' in it. Subsequently, access is 
permitted to all files protected in any way by this passvord. 
After entry, this command is always rendered illegible on the printer 
Listing. | 


02) A read password for the file M.NEU is defined by means of the CATALOG 
command. The password is hereby entered in the catalog, but not recorded 
in the job's password table. The subsequent PRINT or COPY command thus 
Leads to a corresponding error message. 


03) The PASSWORD command enters the password C'OR' in the job's password 
table. The subsequent PRINT and COPY commands are thus performed as 
desired. 


04) This PASSWORD command causes the password table to be deleted; the 
subsequent ERASE command is rejected. 


05) The file M.NEU. KOPIE can be deleted because it is not password- 
© protected. 
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RDTFT OBTAIN INFORWATION FROM TFT AND TST 


3y means of the RDTFT command, the user can output status information from 
the TFT relating to the files and devices currently in use, and also 
obtain information from the associated TST (see the FILE command). 


Operation Operands 


RDTFT LFILE-pathnamel 
Link 
C,LINK= J 
(BLANK pno) 


C,LCINKAGEJIC,SCECURITYIIC,FCCBIIC,VCOLUMES]] 


CALLI ὁ 


FILE=pathname The status information relating to the TFT entry 
associated with "fiLename" is output. Otherwise selection 
of the entry is not dependent on "filename". 


"pathname" stands for: (C:catid:J[S$userid. Jfilename 


catid This operand denotes the catalog identifier associated with 
the file. If this entry is omitted, the default catalog ID 
assigned to the user ID is assumed. 


userid This operand denotes the user identification associated 
with the file. If this operand is omitted, the user's own 
user ID is assumed. 


filename This operand specifies the partially or fully qualified 
file name (up to 41 characters). If the file name does not 
begin with a user ID, it is prefixed by the user ID of the 
job. If the file is a file generation of a group, the 
absolute value of the generation number must be specified. ῷ 
When temporary files are specified, the internal file name 
is output. 


LINK=Link This operand specifies the file Link name. 


If the LINK operand is specified, only status information 
relating to the TFT entries associated with the file Link 
name is output. Otherwise the selection of the entry is 
not dependent on the file Link name. 


=(BLANK,no) This operand specifies the number of the TFT entry which 


Such entries are generated by the OPEN macro if no Link 
name or LINK=C* cc cw." is specified in the FCB (not 
recommended). 


If the FILE and LINK operands are omitted, status 


information relating to all the TFT entries belonging 
to the job is output. 
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SCECURITY] 


FLCBJ 


VCOLUMES] 


RDTFT 


If this operand is specified, the user receives Linkage 
information in the following format: 


STATUS =ACTIVE/INACTIVE [HOLD] [DEV RELEASED] 


RELEASE 
COMMAND =FILE/OPEN CDELAYED= 1 
(RELEASE,KEEP) 
DATA ΞΓΟΑΤΑ ON TAPE VOLUME COUNT] 
where: 


STATUS specifies the file status, the HOLD status, and 
whether the file vas released after being closed. 


COMMAND indicates whether the TFT entries were created 
by means of a FILE command/macro or an OPEN macro. 


DELAYED indicates whether a HOLD command caused a RELEASE 
action to be delayed. 


DATA specifies the number of tape devices that contain 
data. 


The user can use this operand to obtain information 
concerning file security and the retention period. Such 
information is output in the following format: 


RET PERIOD= SECLEV=HIGH]| LOW 
OVWRITE PROTECT-LYES|NOJ BYPASS 
where: 


OVWRITE corresponds to the specifications in the 
OPR qualification (overwrite protection). 
Cf. the BYPASS operand in the FILE command. 


If the operand FCB is specified, the following file 
characteristics are output: 


FCBTYPE=Laccess method] OPEN -Lopen mode] 
RECFORMz[record format] RECSIZE=Lrecord Length] 


BLKSIZE-[bLock size] BUFOFF -[number|LJ 
KEYPOS = KEYLEN = 

LOGLEN = VALLEN = 

VALPROP= DUPEKY = 

PAD = OVERLAP= 

SHARUPD= WROUT =LYES/NONE] 
LABEL  -[tabev type] TPMARK =LYES/NO] 
CODE z[code typel TRANS =CYES/NONE] 
FSEQ =CUNK|NEW] WRCHK =LCLYES/NO] 


If this operand is specified, the device characteristics 
of the file are output in the following format: 


DEVICE -[device type] TSET=[device name] 
VSN/DEV =VOL-SER-#/Cdevice type code] 


The device type code is output only if the device is 
Loaded. 
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ALL This operand specifies that all the information described 
above is to be output for each TFT entry specified. 
Note: 
The TFT entries are output sorted according to their file Link names. 
Output format: 
For files on public disk: 
% LINK=Linkname 
FILE=filename 
For files on private disk: 
*DVOL DEV LINK=Linkname 
FILE=filename 


Remote file access (see also the "RFA" manual) 


If the TFT entry for a file Located in a remote system is to be displayed 
with the aid of this command, the format of the display field is as follows: 


XR LINK=Linkname 
FILE=filename 


"R" means that the file concerned is a remote file. The catalog containing 
the file is specified within the expression FILENAME by means of the "catid" 
entry. ! 


Examples: 


- STATUS information on the TFT entries associated with the file TRICK is 
requested: 


/RDTFT FILE=TRICK 


^ LINK=EDRPRIMR 
FILE=TRICK 

^ LINK-IOOLINK 
FILE=TRICK 


= STATUS information on the TFT entry associated with the file Link name 
EDTISAM is requested, together with additional details on file security: 


/RDTFT LINK-EDTISAM,SECURITY 
% LINK=EDTISAM 
FILE=TRICK 
RETENT. PERIOD -00015 SECLEV = HIGH 
OVWRITE PROTECT=NO 


- Information on the HOLD status and the success of the RELEASE action is 
obtained using the LINKAGE operand: 


/HOLD EDTISAM 
/REL EDTISAM 
/ROTFT LINK=EDTISAM,LINKAGE 


% LINK=EDTISAM 
FILE=TRICK 
STATUS = INACTIVE HOLD 
COMMAND = FILE DELAYED = RELEASE 
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RELEASE DELETE TFT ENTRY 


The RELEASE command deletes an entry in the Task File Table (TFT; see the 
LINK operand in the FILE command) by means of specifying the corresponding 
file Link name. ALL private volumes and private devices Linked to this 
entry, i.e. all those requested for the associated file, are released. 


Operation Operands 
RELEASE 
Clink] 
REL 
Link This operand specifies the file Link name of the TFT entry. 
Ç If "Link" is omitted, the first TFT entry with the Link 
name CT cc ww..." is processed. 


Notes: 


- If there is more than one active file on a private volume due to be 
released, this volume is not released until a RELEASE command has taken 
effect for each active file. 


- The RELEASE command is ignored if the associated TFT entry has previously 
been placed in the HOLD status by means of the HOLD command. RELEASE 
processing is not initiated until the HOLD status is canceled by a DROP 
command, or until the end of the Job. 


- If a file was exclusively reserved with the FILE operand of a SECURE 


command, and subsequently processed, the RELEASE command ends this 
reservation. 
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RESTART START PROGRRH AT CHECKPOINT 


The RESTART command Loads a program with the status it had when a CHKPT 
macro was encountered. 


The command can be used in interactive and batch modes. 


Operation Operands 


RESTART pathnameil ,page][,LOAD] 


YES 
tente | 
NO 


[ ,IDLENTJ =chkptname] 9 


filesectno 
C,VSEQ= J 


LAST 
C,CHKPT=number] 


pathname2 
L,DUMMY- 1 
(pathname2,...) 


[ ,MONJV-2jvname]l 


"pathname1" stands for: [:catid:J[Suserid.Jfivlename1 
"pathname2" stands for: [:catid:J[Suserid.]fivlename2 


catid This operand specifies the catalog identifier to which the 
file belongs. The file must be Locally available. If this 
entry is omitted, the default catalog ID assigned to the 
user ID is assumed. 


userid This operand specifies the user identification to which 2 
the file belongs. If the operand is missing, the user ID of 
the LOGON command is assumed. 


filenamel This specifies the name of the file which was created by 
the CHKPT macro and which contains the program to be Loaded. 


page This operand specifies the PAM block number at which the 
checkpoint records begin. These records are generated by 
the CHKPT macro and this number is output to SYSOUT. The 
system then uses this information from the checkpoint 
records for the restart. 


LOAD Once the program has been Loaded again, it should not be 
started; the system reverts to command mode (cf.' the LOAD 
command in the "ControL System Command Language" manual). 


CHECK=YES This operand checks whether the internal file names of the 


files opened during the restart have been changed. The 
restart is aborted if an internal file name has changed. 
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=NO This specifies that an update of the internal file name is 
to be ignored. 


IOCENTJ =chkptname 
This operand specifies a 6-byte identifier for the CHKPT 
macro. 
This identifier is output to SYSOUT together with a number 
(see the "page" operand) during checkpoint processing 
(CHKPT). 


If two checkpoints with identical identifiers exist for a 
checkpoint file, IDENT designates the Last checkpoint which 
has been sete The checkpoint set earlier can only be 
identified using the "page" operand. 

If neither "page" nor IDENT has been specified, the program 
is started at the Last checkpoint. 


Note: 


e Specification of this operand is possible only if the 
checkpoint file is a disk file. 


VSEQ=filesectno This designates a file section number at which the restart 
begins. m 


O < filesectno < 255 

This operand may only be used in the case of files which 
have standard Labels and which have been cataloged with 
FSEQ=1 (cf. the FILE command). ! 
The "page", LOAD and IDENT operands must not be used 
together with VSEQ. 

Note: 


If this operand is omitted, the default value of 0 is 
assumed. 


=LAST This operand designates the Last file section. 


CHKPT=number This specifies the number of checkpoints which are passed 
© through when restoring unusable file sections. 


Possible entry: O < number < 255 

This operand permits resetting at a given checkpoint and 
abortion after the number of written checkpoints has been 
reached. The checkpoint identifiers can be re-used. 


Note: 


If this operand is not specified, the default value of 0 is 
assumed. 
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DUMMY=filename2 Tne file is treated Like a DUMMY file. 


A maximum of 255 files can be specified. 
Note: 
= SYSFILE is not permissible 


- The CHKPT file may be declared to be a DUMMY file only 
if the CHKPT operand has not been specified. 


The following operand is only available to users who have the appropriate 
system components for job variables: 


MONJV-jvname This operand specifies the name of a job variabLe uhich 


monitors the newly started program. The user can then use 
this job variable to address his program. 

While processing the newly started program, the operating 
system sets the job variable to the value SR, ST or SA. 
See also the "Job Variables” manual. 


Notes! 


The job vhich caused the restart requests the same memory which the 
interrupted job had vhen the checkpoint vas set. In addition, the 
checkpoint determines whether the newly started job operates in 
interactive mode or another mode. Files which vere open when the program 
and operating system statuses vere set are also open during restart. EAM 
files are, however, not restored. 


If these files are file generations, changing of the base value with 
respect to the CHKPT time should be avoided if at all possible. The 
reason for this is that the RESTART command ignores any updating of the 
file generation group which might have taken place between the CHKPT 
and RESTART times, and assumes the status valid at checkpoint time. 


It is therefore not advisable to make any further changes to the file 
generation groups used in the CHKPT task up until the RESTART point. 


The RESTART command may be used only if the system file SYSDTA is combined 
with SYSCMD and if the system files SYSIPT, SYSLST and SYSOUT have not 
been assigned to a file. 


The BS2000 version and the system configuration valid for the RESTART 
command must also be valid when the CHKPT macro is issued, otherwise 
the user receives an error message. 


Before the RESTART command is used, those tapes which were being 
processed at checkpoint time must be mounted. The checkpoint data 
contains the information which the system needs to reposition the tapes 
to the appropriate block. 
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- The RESTART command cannot be issued in the following two cases: 


1. If all the SYSFILE allocations (i.e. of all the opened procedures) 
saved in interactive mode by means of the CHKPT macro contain one or 
more procedures which have been interrupted, the RESTART command 
cannot be used in batch mode. 


2. If all the SYSFILE allocations saved in batch mode by means of the 
CHKPT macro contain one or more allocations of SYSOUT to a catLoged 
file, the RESTART command cannot be used in interactive mode. 


In both of the above cases an error message is output and the job is 
aborted. 


- In the case of insufficient cLass 5 memory, RESTART processing is 
aborted with an error message. 


= It should be noted that the maximum Life-span of 8 temporary five starts 
e at LOGON and ends vith LOGOFF. 
For this reason the user must either restore the temporary fives 
before issuing the RESTART command or decLare the temporary fives 
as dummy files in order to perform a restart (FCB, FILE : CHKPT=DUMMY 
or RESTART : DUMMY= ) 


If, in the course of CHKPT processing, the system determines that 
temporary files are being used, the Left-justified byte of R15 (secondary 
indicator SI) is set to X'4á4' to warn the user, since the Limited 
Life-span of temporary files creates restrictions on the restart 
Capability of the checkpoint which has been written. 


When the RESTART command is processed, a check is made for each temporary 
file of the checkpoint task to determine whether it is to be stored as 

a dummy file or whether a temporary file with the same name (and with 

the same file attributes) has been generated in the RESTART task. An 
error message to the effect that the temporary file does not exist may 
appear. 


- CHECKPOINT/RESTART cannot be used to increase the Life-span of a 
temporary five. 


e - After RESTART, only temporary files of the user's own task can be 
accessed; the user cannot access temporary files of the CHKPT task 
unless the Latter is identical with the restart task. 


- If processing of the /RESTART command is aborted with the message 
E305 PAM I/O-ERROR (xx), the following additional information is output: 


Xx 

Χ 06" REQM error 

X'08' Catalog error (e.g. file does not exist) 

X'*OC' A device cannot be reserved 

X'10' A file has been opened with "sharupd" 

X'14' No extension for slot segment exists | 

X°18" Response "T" to message DDEE or error when writing to checkpoint 
file 

X'1C' VSN not the same or error on ISAM reopen 

X'20' Error in FCB | 

X'24' The number of tape devices for a file is smaller than the number 
at checkpoint time. 
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Program monitoring (see also the "Job Variables" manual) 


- The status indicator in the program-monitoring job variable is set to 
"SR" at RESTART time. 


- If "jvname" is not accessible at the time the command is processed, an 
error message is output to SYSOUT and processing is terminated. 


Network catalog management (see also the "MSCF Multiprocessor System" manual) 


The RESTART command must be issued on the same system as the CHKPT macro 
(same processor, same home pubset, same EXEC). 
Example? 


The third tape of a volume series has been damaged. Reconstruction takes 
place by means of the RESTART command from the previous checkpoint. 


/RESTART BAND. SICH, VSEQ=2,CHKPT=1 


The program is terminated after the first checkpoint has been written. 
No update of the catalog takes place. 
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VERIFY RESTORE FILE 


The function of the VERIFY command is to make files (also file generations 
and file generation groups) accessible again which were not properly 
closed on account of a system failure or job abortion. 


The command can be used to: 


- release a LOCK on a Locked tape or disk file, thus making it available 
for general access again; 


- restore a disk file. For this purpose, the catalog entry is updated, the 
file is closed (if necessary) and, in the case of ISAM files, the file 
is restored on the basis of the existing data records. 


e Operation Operands 
VERIFY pathnamel1L,pathname2] 
YES 
[  REPAIR={ABS}] 
NO 


c suPPoRT=| h 
PRDISC 


”pathname1” stands for: [:catid:][$userid.]fiLename1 
"pathname2" stands for: [:catid:][$userid. ]filename2 


catid This operand denotes a catalog identifier associated with 
the file. If this entry is omitted, the default catalog ID 
assigned to the user ID is assumed. 


userid This operand denotes the user identification. If this 
© operand is omitted, the user's own user ID is assumed. 
fivLename1 This operand specifies a fully or partially qualified file 


name, or the name of a file generation, file generation 
group or temporary file. 


filename2 This operand applies only to ISAM files; it specifies the 
name of the file in which the ISAM file "filename1" is to 
be restored. If this entry is omitted, the ISAM file is 
restored in a work file provided by the system. In the 
case of an ISAM file on private volumes, where the data 
and index blocks are Located on different disks, the file 
will be restored only if "filename2" has been specified. 
“filename2" must be different from “filename1" and be a 
fully or partially qualified file name, i.e. the entry is 
ignored if it is the name of a file generation or of a 
file generation group. 


Specification of a temporary ISAM file is permissible. 
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REPAIR 


SUPPORT-PUBLIC 


Note: 


If a user ID other than the user's own is specified in 
a path name, the file must be shareable. 


=YES PAM: 


SAM: 


ISAM 


=ABS PAM: 


SAM: 


ISAM: 


=NO PAM: 


SAM: 


ISAM: 


The following operands are used when restoring files: 


The file is unlocked. If the file is marked as an 
open file, a privileged close operation is performed. 
The pointer to the Last PAM block remains unchanged. 


The file is unlocked. If the file is marked as still 
being open, the pointer to the Last PAM bLock is set 
to the highest page containing data. The file is 
cLosed. 


The file is unlocked and, if it is marked as being 
opened, it is restored. 


The file is unlocked, after which the pointer to the 
Last PAM block is set to the highest PAM page 
containing data. 


The file is unlocked. Even if the file is not marked 
as being open, the pointer is set to the highest PAM 
page number containing data. The file is closed. 


The file is unlocked and restored. 


The file is merely unlocked (removal of the entry 
from the table of Locked files). Thereafter the 
file is still not regarded as being closed, i.e. 
it will be Listed in response to FSTATUS, 
STATE=NOCLOS, and -with VERIFY. ..., REPAIR=YES, 

it will be regarded as a file to be repaired. 


The file is merely unlocked. 


The file is merely unlocked and, if it is still 
marked as being opened, a privileged close operation 
is performed and the pointer to the Last PAM bLock 
is set to the highest PAM page number containing 
data. 


This operand selects files on public volumes for 


restoration. 


=PRDISC This operand Limits restoration to files Located on private 


volumes. 


The SUPPORT operand is meaningful only when 


"fiLename1" specifies a partially qualified file name or 
the name of a file generation group. 


Notes: 


Following the message "FILE NOT ACCESSIBLE DUE TO SPACE PROBLEM" the 
file can no Longer be made available with VERIFY. In this case it is 
possible to give only the command /ERASE.... ,CATALOG (even for PUBLIC 


files). 
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- In order to be able to cancel a file Lock, the job which caused the 
Lock must have been terminated by the system with the console message 
"TASK PENDED INDEFINITELY". 


For files declared as exclusively reserved via the SECURE command, the 
user can cancel the Lock; in the case of disk files, only the system 
administrator is authorized to do so. 


- If file access was interrupted while data buffers were Located in main 
memory, the Last modifications made may be missing from the restored file. 
This is because a buffer is not written to external storage until it is 
full. 


Notes on the restoration of ISAM files: 


- If the entry “filename2" is omitted for an ISAM file on public volumes, 

the file is restored in a work file provided by the system. "fiLename1" 

e is then deleted, without the DESTROY entry (see the ERASE command), and 
the work file is renamed "filename1". 


- If the entry "“filename2" is omitted for an ISAM file on private volumes, 
the file is restored in a temporary work file on public volumes. The 
work file is subsequently copied to the file "fiLename1" and the work 
file deleted, with the DESTROY entry (see the ERASE command). This 
: procedure can be extremely time-consuming, and thus it is more convenient 
to specify "fivlename2". 


- If a file "fivLename2" is defined in the VERIFY command, the ISAM file 
"filename1" is restored on this file, “filename1" remaining unchanged. 
If "fivename2" is Located on private volumes, or if "filename1" is a 
file on private volumes, the user must catalog the file "filename2" 
before issuing the VERIFY command. If the data and index blocks are 
Located on separate volumes, the user must also allocate space for 
"filename2" via a FILE command. 


=- With ISAM files, the data buffers are written back to the disks as 
soon as a nev data bLock has to be fetched into main memory. This 
may resuLt in the Last modifications made being omitted from the 
restored ISAM file. If, however, WROUT=YES vas specified in the FILE 
e command or macro, the effect of the error is negligible, since the data 
buffer is written back to the disk after each modification. 


- Records having the same index and containing the same data are included 
in the restored file once only. 


. No space is reserved in the data blocks of the restored file for 
subsequent additions; this corresponds to PAD=0 in the FILE command. 


- ISAM files whose data and index blocks are on separate private volumes 
can be restored with the VERIFY command only when BLKSIZE=STD is 
specified. 


- If an ISAM data block contains data which cannot be assigned to any 
defined record, the whole block is saved to a PAM file bearing the name 
"S.filename1. REPAIR". Once VERIFY processing has been completed, this file 
is available to the user for his own attempts at restoration. If the file 
name gets to be too Long, filenamel is truncated accordingly. 


= As 8 copy of the file is created when restoring ISAM files and this copy 
is part of public space, the user must make first make sure that there 
| is sufficient public space available. If "fiLename1" is 8 temporary five, 
© it is advisable to specify "filename2" as a temporary file too. 
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3.2 DEVICE MANAGEMENT 


SECUREC-RESOURCE-ALLOCATION] REQUEST RESOURCES 


The SECUREL-RESOURCE-ALLOCATION] command reserves resources required by a 
job during its execution. This reservation ensures that a subsequent request 
for access to these resources will not be rejected by the system. 

These resources may include: 

- disks 


- files, file generations and file generation groups. 


Reservation of the file also results in reservation of the disk, and 
in turn, reservation of the devices. 


An existing reservation can be deleted by means of: 

- The RELEASE command: 
This cancels the reservation of the file and, if necessary, of the 
associated disk. The same device reservation as before is maintained. 
If disks or devices assigned to the file are also implicitly reserved 


by means of other files or disks, these are not released until all system 
references have been dealLlocated. | 


- Renewal of the SECUREL-RESOURCE-ALLOCATION] command 

- The WHEN command: 
This command has the same function as SECUREL[-RESOURCE-ALLOCATIONJ 
without the need for specifying the operand. 

- End of gob (LOGOFF). 


The SECUREL-RESOURCE-ALLOCATION] command can be used in both interactive 
and batch mode. 


The following two commands are available for reserving resources: 

SECURE 

SECURE-RESOURCE-ALLOCATION 

However, the functional scope of the SECURE command, whose syntax is 
compatible with Version 7.5, is restricted. As far as internal processing 


is concerned, there is no difference between the two commands, i.e. the 
notes on the SECURE-RESOURCE-ALLOCATION command also apply for SECURE. 
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SECURE format 


Operation Operands 
mos CVOL=(vsn/type,...)] 
SEC [,FILE-(pathname[/EX],...)] 


VOL-(vsn/type,...) 
This operand specifies the volume serial number (6 bytes 
Long) and the device type for the volume to be secured. 
Volumes reserved are shareabLe. 


The entries in the VOL operand must be enclosed in 
parentheses, and individual entries separated by commas. 
e Up to 16 entries are possible. 


The following disk storage units may be specified: 


D3455 or D5881 
D3465 or D5882 
D3468 
D3470 or D5804 
D3475 
D3480 


FILE= This operand reserves the specified file, file generation 
or file generation group. 


If more than one file name is specified in the FILE 
operand, they must be separated by commas and enclosed in 
parentheses. Up to 48 entries are possible. 


=pathname “pathname” stands for [:catid:][$userid. ] filename 
=catid This operand specifies the identifier of the catalog to 
which the file belongs. 
If this entry is omitted, the default cataLog ID assigned 
o to the user ID is assumed. 


-userid This operand specifies the user ID to which the file 
belongs. If no entry is made, the user's own ID is assumed. 


=filename This entry specifies the fully qualified name of a file 
or file generation which has already been cataloged. 


=(filenamel[EX],...) 
This operand specifies exclusive reservation of a file, 
file generation or file generation group; i.e. in addition 
to any existing implicit reservation of volumes and 
devices, a file Lock is effected, thus preventing any other 
job from accessing the file/files. 


If "fivename" is the name of a file generation, the 


appropriate reservation is performed, and the associated 
file generation group is Locked. 
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If "filename" refers to a file generation group, the entire 
group is blocked against foreign access. 


If one of the requested resources is not available, a 
distinction is made between interactive mode and batch mode 
in subsequent processing: 


Interactive mode: The command is rejected with an 
appropriate message 


Batch mode: The job is put into a wait queue, the 
SECURE-QUEUE; there is no restriction on 
the waiting time, which Lasts for as Long 
as it takes to make all requested 
resources available simultaneously. 
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SECURE-RESOURCE-ALLOCATION format 


Operation Operands 
SEC-RES *NO 


(VOLUME=vsn, TYPE=device 
CDISK= J 
EXCLUSIVE 
c -ALLOcATrON=| pu 


SHARED 
*NQ 


C,FILE= αν. 1 
dL 


(NAHE=pathnanel ,ALLOCATZON=| 
SHARED 


IASK-SID 
L WAET=(CTIHE=| jn 
n 


The flag "L" indicates that the operand can be specified in List 
form, e.g.» (0p1,0p2,...). 


DISK operand 


VOLUME=vsn This operand specifies the vsn of the device which is to be 
reserved (maximum of 6 characters). 


TYPE=device This operand specifies the device on which the disk is to be 
operated. "device" may be any of the following: 


D3455 
D3465 
D3468 
D3470 
D3475 
D3480 


ALLOCATION= This specifies the mode of reservation used to reserve 
the disk. 


-EXCLUSIVE 


ExcLusive reservation means that the resource cannot be 
used by other jobs. 


This is the default value, specifying that other jobs 
may also use the device. 


UB05-J-255-5-76500 


3-95 


SECURE-RESOURCE~ALLOCATION 


FILE operand 
NAME=pathname 


catid 


userid 


filename 


ALLOCATION= 


"pathname" stands for (C:catid:][$userid. ]filename 


This specifies the identifier of the catalog to which the 
file belongs. If this entry is omitted, the default catalog 
ID assigned to the user ID is assumed. 


This specifies the user ID to which the file belongs. 
If the entry is omitted, the user's own ID is assumed. 


This operand specifies the fully qualified name of a file 
or the name of a file generation which has already been 
cataloged. Both system and user files can be reserved; 

the only thing that is verified is whether or not the file 
or file generation exists. If it does not exist, the job is 
not pLaced in the device queue; an error message is issued 
instead. In batch mode, a branch is made to the next STEP, 
ENDP, ABORT, ABEND or LOGOFF command (cf. the “Control 
System Command Language" manual). 


ALL disks belonging to the file are reserved and mounted. 
Disks are always regarded as being shareable. 


This operand specifies the reservation mode of the file. 


Both the file and the corresponding disks or devices are 
reserved and shareable. The file can be opened by other 
jobs (in both read and write mode), i.e. only implicitly 
required disks and devices are reserved. 


=EXCLUSIVE 


HAIT operand 


TIME- 


-TASK-STD 


The file can only be opened by the job which reserved it. 
Corresponding disks and devices are SERVA shareabLe as far 
as reservation is concerned. 

ExLusive reservation of the file is DossipUb onLy aT it 

is not being used. 

If the file is a file generation group, the entire file 
generation is Locked against access by other users. 


This specifies the maximum period of time the job will 
vait for execution of the reservation request. 


A distinction is made betueen interactive mode and batch 
mode. | 


Interactive mode: The command is rejected if the request 
for reservation cannot be met. 


Batch mode: In principle, the system waits for 
mounting and release of resources for the 
Length of time specified. If the requests 
have not been fulfilled and the waiting 
period has expired, a branch is made to 
the next STEP, ENDP or LOGOFF command. 
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-n This operand specifies accuracy, in minutes. The maximum 
value is 43,200 seconds (= 12 hours). If Less than 180 
seconds are specified, the command is rejected if mounting 
of a disk is required or if confirmation on the part of the 
operator is required. 


Notes: 
- The SECURE command is allowed only when no program is Loaded. 


- Other users' files can be reserved only if they were entered in the 
catalog with SHARE=YES (see the CATALOG command). 


- Files under the ID of the system administrator can only be exclusively 
reserved by jobs running under this ID. 


- Each SECUREL-RESOURCE-ALLOCATION] command (including those without 
6 operands) first releases all previously reserved private resources 
(implicit RELEASE). 


- If a volume which has not yet been mounted is reserved using the 
SECURE command, a MOUNT message appears on the console. 


- A request for a volume made via the FILE operand in the SECURE command 
is referred to as implicitly requested, otherwise it is referred to 
as explicitly requested. 


- Any attempt to reserve a public volume explicitly will be rejected. 


- A resource is considered exclusively reserved if no other job can use 
it while it is reserved. If the system guarantees free access while it 
is reserved without prohibiting other jobs from using it, the resource 
is termed shareable. 


- If one of the resources requested cannot be secured, no reservation is 
carried out at all. Depending on the type of job and the specified WAIT 
operand, if any (SECURE-RESOURCE-ALLOCATION command only), either an 
appropriate message is issued by the system or the job is held in the 
SECURE queue until all the resources requested are available for the job 

e or until the specified waiting time has expired. However, a branch is 
made to the next STEP or LOGOFF command if the device or number of 
devices requested are not available. 


- If a SECURE command is rejected (resources not available, for example), 
all the volumes previously allocated to the job are released. 


- If the operator refuses the request for a resource (MOUNT message on 
the console), no reservation of any sort is undertaken and, in batch 


mode, control is passed to the next STEP or LOGOFF command (see the 
“Control System Command Language" manual). 


- If a file which extends over several private volumes is reserved, all 
the volumes are reserved. 


- The system rejects a SECUREL-RESOURCE-ALLOCATION] command if the calling 
job has opened files on exclusively reserved private volumes. 
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- Files on private volumes can be opened in the following cases: 


- if the SECURE command originates from a procedure file which is itself 
Located on private volumes; 


- if a file on private volumes has previously been assigned with the 
SYSFILE command. 


Such a file should be treated as a resource which, when the SECURE 
C-RESOURCE=ALLOCATION] command is processed, must first be released 
before new resources can be reserved. 


- The reservability of a disk is dependent on the values given in the 
USER-ALLOCATION, SYSTEM-ALLOCATION and OPERATION-CONTROL operands 
and in the SET-DISK-DEFAULTS or SET-DISK-PARAMETER operator command. 
These values can be interrogated by the user by means of either the 
/SHOW-DISK-STATUS command or an appropriate DSTATUS macro. 


- Shareable private disk (SPD): Ω 


A SECURE FILE command for files which reside on an SPD is entered in the 
F1 LabeL of the private disk. Other processors accessing this SPD 
respect this SECURE command. 


- If a pubset specified by means of "catid" in the FILE operand is not 
available Locally and not contained in the RFA table of the job, the 
command is rejected with an error message. It is therefore not possible 
to wait for the Local availability of a pubset. 


Remote file access (see also the "REA" manual) 


- The SECURE command cannot simultaneously reserve Local and remote 
volumes. 


- The Local TFT contains entries for all remote files that are processed. 
However, this does not include remote files that are exclusively reserved, 
or remote resources after the /RELEASE command has been issued. 


- Files can also be reserved in a remote system via RFA; however, this 
command may only include files and all of these must be part of the 


same system. 2 
- To prevent a deadlock situation from occuring, a SECURE command without 
operands is passed on to all RFA partner tasks (unless the task is 
itself an RFA partner task) during the release phase at the start of 
command processing. 
- If an RFA partner task is running on a system Less than or equal to 
Version 7.6, the SECURE command must be issued. 
Example: 
A batch job reserves the file X.VORHER using the command: 
/SECURE FILE=X. VORHER/EX 


Thereafter any interactive job attempting to read this file will receive 
the error message “LOCK ERROR 0099”. 
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SHOW-DEVICE-STATUS ^ REQUEST RESERVATION AND MONITORING INFORMATION 


This command provides information on the reservation and monitoring of 
volumes. The information output pertains to volumes which are physically 
online (in contrast to that output by the SHOW-DISK-STATUS command). 

If no volume is online for a device, the display indicates which volume is to 
be mounted on the device. 


The user obtains an output record only for the devices for which his job 
has made a reservation. 


There is no restriction in respect to information output using the 
INFORMATION-SUMMARY operand. 


Operation Operands 
© SHOW-DEVICE-STATUS mn 
UNIT= 


SH-DEV (mn1,mn2,...) 


TYPE-device-typet -ATTREIBUTE]=| h 
attribute 


| ALL 
FANCILYI=device-fanityl ATTRETBUTEJ =Í h 
| attribute 


ALL 
ATTRLIBUTE] = 
attribute 


STD 

SUM[ MARY] 
C, INFCORMATION] = J 

ALL 

SHORT 


UNIT=mn This operand specifies one or more hardware units on which 
information is output; the units are specified via their 
mnemonic device names (2 alphanumeric characters). A 
maximum of 26 units may be specified. 


TYPE=device-type Information is output on all devices of the. specified 
device type. The following device types are possible: 


D3455, D3465, D3468, Disk Storage Units 
D3470, D3475, D3480 
D348E 
FAMILY-device-famivy 
Information is output on all devices which belong to the 
specified family of devices. Possible device families are: 


DISK Disk devices 
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ATTRIBUTE-ALL Information is output on devices with all possible 
attributes. 
-attribute 


Information is output on all devices with the specified 
attribute. Possible attributes are: 


ATTLACHEDJ 
DETLACHED] 
DETLCACH] -PLENDINGJ 
FREE 

DMS 

EXCLLUSIVE] 
PUBLLIC] 


INFORMATION= Specifies the type of information desired. 


-SID A standard output record is output (see output formats). 
When TYPE or FAMILY is specified, only default information 
is supplied. 


=SUMMARY 
A summary of configuration and reservation statuses is 
generated. 


=ALL Output of STD and SUMMARY. 


=SHORT 
Provides a brief description of STD without header and 
without SUMMARY records of the specified family or of the 
specified type. 


Output format 


A header and, for each device, a continuation Line with the values are 
output. Depending on the specification in the INFORMATION operand, four 
output formats are possible. See Table 3-1 for the meaning of the output 
columns and possible values. 


1. 


Output for INFORMATION=STD 


Header: 
MNEM  DEV-TYPE CONF STATE POOL VSN DEV-A PHASE ACTION 
Values: 
mn device short pool vsn device volume action 
type configuration attribute allocation phase state 
state state 
Note: 


During a REMOUNT procedure, a vsn can simultaneously appear in two 
output records, namely in the record of the device on which the volume 
is physically online and in the record of the device on which the volume 
is to be mounted. 
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2. Output for INFORMATION=SUMMARY 


Header: 


DEV-TYPE AVAIL PRE-/IN-USE RES-BY-MN RES-BY-TYPE ATT DET DET-P 3 


VaLue Line: 


dev # of still (κ) 8 of devices reserved # of devices 
type available with without that are 
devices mnemonics attached, detached 
detach-pending 


(*) : Number of devices with the status PREMOUNT,MOUNT(ing), IN-USE 


3j. Output for INFORMATION=ALL 


e Formats 1 and 2 are output. 


4. Output in brief for INFORMATION-SHORT 


Value Lines without header and with the following elements: 


mn , Letter of , short device , spd 
conf state alloc state indicator 
Values: 


A(ttached) , D(etached) 
P (detach-pending) 


Letter of conf state 


spd indicator = *, provided that SPD features are present 


short device alloc state = tsn of the exclusively reserving task 
FREE , DMS , PUB(Lic) 


This is followed by output of INF=SUMMARY. 
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SHOW-DISK-DEFAULTS | INTERROGATE DEFAULT VALUES FOR DISK PARAMETERS 


The SHOW-DISK-DEFAULTS command provides information concerning the default 
values for the DISK parameters which have been set using the operator command 
SET-DISK-DEFAULTS. 

Operation Operands 


ως oae 


SH-DISK-DEF 


Output format 


One header and one value Line are output. See Table 3-1 for the meaning of 
the output columns. | 


Header: 
ASSIGN-TIME USER-ALLOCATION OPERATOR-CONTROL. 


Value Line: 


USER , NO , ALL NO , ALL 
MOUNT , EXCL(usive) , EXCL(usive) , 
OPERATOR SHARE SHARE 
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SHOW-DISK-STATUS ^ INTERROGATE RESERVATION AND DISK PARAMETERS 


The SHOW-DISK-STATUS command provides information on reservation and DISK 
parameters as well as on volume monitoring for the specified disks. The 
information which is output refers to the reserving volume, irrespective 
of which volume is physically online (as opposed to the SHOW/DEVICE-STATUS 
command). 


The user only obtains an output record for those disks for which his job 
has made a reservation. 


Operation Operands 
SHOW-DISK-STATUS mn 
UNIT= 
e SH-DISK (mn .mn »9.o) 
1 2 
vsn 
L| | VOLCUMEJ = ] 
(VSN ,vsn peso) 
1 2 
NTTREZBUTED- | 
attribute 
t INFCORHATION}=] h 
PARLAMETER] 

UNIT=mn This operand specifies the disk devices on which 
information is output by means of their mnemonic device 
names (2 alphanumeric characters). Up to 26 units can be 
specified. 

© VOLUME=vsn This operand specifies the disks on which information 
is output by means of their volume serial numbers (maximum 


of 6 characters). Up to 8 vsn's may be specified. 


ATTRIBUTE Information is output on disks with all possible attributes 
(default value). 


=attribute 
Information is output on all those disks that include the 
specified attribute, which may be one of the following: 


FREE 

EXCLCUSIVE] | volume aLLocation status 
SHARE 

PUBLIC] device allocation status 
ONLINE 


MOUNT | volume phase 
IN-USE 
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CANCCELLED] 

NO-DEVLICE] 

RECLOVER] action state 
DISMOUNT 

UNLOCK 

SVL-UPDLATE] 


DMS ] use mode 
SPECIAL 


STD 
NLONJ -STD Label type 
BS1000 


INFORMATION= Specifies the type of information desired. This operand is 
valid only in connection with the UNIT OR VOLUME specifica- 
tion. Only INFORMATION=STD is possible for ATTRIBUTE. 


-SID For each disk, a record with global reservation and 9 
monitoring information is output. 


=PARAMETER 
The parameters set by the operator are output. Parameter 
values which have been set as the default values are 
identified by "(D)". This operand cannot be used to 
interrogate information on public disks. 


Output format: 

A header and, for each specified disk, a value Line are output. Depending on 
the specification in the INFORMATION operand, five output formats are 
possible. See Table 3-1 for the meaning of the output columns and possible 
values. 


1. Standard output record 


Header: 
MNEM VSN USE LABEL DEV-A VOL -Α PHASE ACTION 
VaLues: - 
mn vsn use Label device voLume voLume action 
mode type allocation allocation phase state 
state state 


2. Output record for INFORMATION=PARAMETER 
Header: 


MNEM VSN TYPE  ASS-TIME USER-ALLOC  OP-CTL SYS-ALLOC ACCESS 


Values: 
mn vsn device assign user operator system access 
type time aLLocation access aLLocation mode 
type controL mode 
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Hotes: 


1. In the case of public disks, only mn and vsn are output when the 
parameter INF=PAR is specified. 


2. If more than one disk with the same vsn exists within a system, only 
one record is output when INF=PAR is specified. 
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SHOW-MOUNT-PARANETER = INTERROGATE MOUNT SPECIFICATIONS 


SHOW-MOUNT-PARAMETER provides information on the specifications made by the 
operator using the MODIFY-MOUNT-PARAMETER command reLating to the mounting 
and demounting of volumes. 


Operation Operands 


SHOW-MOUNT 
-PARAMETER 


SH-MOUNT -PAR 


Output format 


One header and one vaLue Line are output. See TabLe 3-1 for the meaning of 
the output coLumns. 


Header: 
TAPE-MOUNT  DISK-MOUNT ALLOCATE=TAPE UNLOAD-RELEASE-TAPE 
VaLue Line: 


YES , NO YES , NO YES , NO YES , NO 
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SHOW-RESOURCE-ALLOCATION ^ INTERROGATE TASK RESERVATIONS 
AND OPEN OPERATOR ACTIONS 


The SHOW-RESOURCE-ALLOCATION command provides information on reservations 
and on operator actions which are still open for the user's own job. 


Operation Operands 
SHOW-RESOURCE *OWN[ -TSNJ 
-ALLOCATION ISN- 
L tsn ] 
SH-RES MONE JV] monjv 
| ITNzsX'itn' 
30BL -NAMET 
e C,IDCENTIFICATION] -| 3 1 

USERL -IDENTIFICATLONI] 


t INFCoRHATIONI =| ha 
ACTCIONS] 


=* ~ This operand provides information on the user's own tsn 
(default value). 


-tsn Designates a job by means of the task sequence number. 
The user may specify only his own tsn. 
JOB-NAME=j0b-name 
This operand designates a job by means of its job name. 
ITNzX'itn' This designates a task by means of its internal task number. 
When X'O' is specified, the user obtains information on his 
own ITN. 


C IDENTIFICATION- This operand controls the occupancy of output field NAME/ID. 


The job name is entered in the field NAME/ID (default 


value). 
-USER-IDENTIFICATION 
The user ID is entered in the field NAME/ID. 
INFORMATION This specifies the type of information desired. 
=RESOURCES 


A record concerning every resource reservation for the 
specified task is output (default value). 


=ACTIONS 
A record is output for each open operator action for a 
voLume of the specified task. 
Operator actions include: 
Mounting, mounting a vrite-enabLle ring, rectifying INOP, 
advance mounting, remounting, etc. 
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Output format 
One header and one value Line are output. Two output formats are possible, 


depending on the specification in the INFORMATION operand. See Table 3-1 
for the meaning of the output columns and possible values. 


1. Output for INFORMATION=RESOURCES 


Header: 

MNEM ^ DEV-TYPE VSN  VOL-A TSN NAME | ID PHASE 

Values: 

mn device vsn volume tsn cf. volume 
allocation allocation ' IDENTIFICATION phase 


type state operand 


2. Output for INFORMATION=ACTIONS 


Header: 

MNEM DEV-TYPE VSN VOL=A TSN NAME | ID PHASE 

VaLues: 

mn device vsn volume tsn cf. voLume 
allocation allocation IDENTIFICATION phase 


type state operand 
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Meaning of the output columns in conjunction with the SHOH commands 


Keyword Used in Meaning 
command 


ACCESS SH-DISK READ: Defines how the disk is used in 
(ΙΝΕΞΡΑΒ) PPD mode (PPD = Protected Private 
Disk; chargeable product). In 
this mode of operation the data 
on the disk is read only, no 
write access is allowed. 

WRITE: Both read and write access are 
permitted for the disk. 

ALL: The final ACCESS value is not 
defined until the disk is 
reserved; this is dependent upon 
the generation specification of 
the device on vhich the disk is 
mounted: 

*POOL-NO|SH results in the 
setting of ACCESS=WRITE 
*POOL-SW results in the setting 
of ACCESS=WRITE 


This value is independent of the position 
of the WRITE INHIBIT switch. 


ACTION SH-RES Indicates vhich reservation or mount 
SH-DEV procedure started by the voLume monitoring 
SH-DISK facility is presently being executed. 

This may be initiated by the following 

actions: | 


- Operator intervention (inadvertent 
demounting of a volume still being 
used) 

- Commands (DETACH, MOVE ...) 


- Device Error Recovery (DER), e.g. in 
the event of INOP 


- User request (MOUNT message for volumes 
not yet mounted). 
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Keyword Used in Meaning 
command 


ACTION The following status conditions may occur: 


continued 
CANCELLED: 


DISMOUNT: 


INOP: 
MOUNT: 
NO ACTION: 


NO DEVICE: 


POSITION: 


PREMOUNT: 


RECOVER: 


REMOUNT: 


SVL-UPDATE: 


UNLOCK: 


WP-MISSING: 


3-110 


A tape or disk is permanently 
Locked against use; the 
canceLation can no Longer be 
changed. 

Either a REMOUNT message is 
pending for the same voLume on 
another device, or a REMOUNT 
or MOUNT message is pending 
for another voLume on the 
same device. 

The device is temporarily 
unavailable (inoperable). 

The response to a MOUNT 
message is pending for the 
volume in question. 

No interrupt. 

Due to a previous reconfi- 
guration command (DET, REM) 
there is no Longer any device 
allocation for a volume which 
has been reserved. 

A tape being used is reposi- 
tioned. 

The response to a PREMOUNT 
message is pending for the 
voLume in question. 

Interrupt processing is 
taking place for the volume 
in use; the exact type of 
processing is not specified. 
A remount operation is being 
performed. 

The system reservation Log 
is being stored on disk. 

An UNLOCK gob for a system 
ID stored in the SVL is being 
performed. 

Either the urite-enabvle ring 
is to be mounted for a tape 
or the write protection for 
a disk is to be cancelled. 
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Keyword Used in Meaning 
command 


ASSCIGN] -TIME SH-DISK In the case of private disks, this 
(ΙΝΕΞΡΑΒ) defines the time at which a disk is 
SH-DISK-DEF reserved or released in USE=DMS mode 

(SH-DISK INF=PAR). 

With SH-DISK-DEF the vaLue for ASSIGN-TIME 

defines the time of reservation or release 

for all the disks for which this value vas 

not specifically set. 


ATT SH-DEV Shows the number of devices in the 

(INFZSUM) ATTACHED state which beLong to the device 
type specified in the output (independent 
of the reservation). 


© AVAIL SH-DEV Shows the number of devices still free 
(INFZzSUM) (available) for the device type defined 
in the output. 


CONF -STATE SH-DEV Indicates the configuration status 
(ATTACHED, DETACHED, DET-PENDING) of 
the specified device, from which the 
availability of said can be deduced. 


DET SH-DEV Indicates the number of generated devices 
CINF=SUM) of the specified type which are not 

available as a result of their 

configuration status (DETACHED). 


DET-P SH-DEV Number of devices of the type in question 
CINF=SUM) which the system still needs to fulfil 

user requests and which are to be detached 

after they have been released. 

New reservation of these devices is no 

Longer possibLe. 
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Meaning of the output columns 


Keyword Used in 
command 
DEV-A SH-DEV 
SH-DISK 
DEV-TYPE SH-RES 
SH-DEV 
; = 
MNEM SH-RES 
SH-DEV 
SH-DISK 
Bes d 
OP-CTL SH-DISK 
OPERATOR-CONTROL (ΙΝΕΞΡΑΒ) 


32118 


Meaning 


Provides information on the type of device 

reservation: 

FREE : The device is not yet reserved, 

i.e. it is still free. 

The device in question is impli- 

citLy reserved by the DMS appli- 

cation on the mounted private 

disk. 

The device is implicitly 

reserved by an active public disk 

which has been mounted. 

TSN of the job exclusively 

reserving the device. 

Either: 

- the TSN is requested by means 
of SECURE UNIT, or 

- in the case of disk devices, 
the job making the reservation 
uses the assigned disk for 
a USE-SPECIAL application 
(PHASE-IN-USE or MOUNT). 


DMS : 


PUBLIC: 


tsn 


TSOS type (D3465, UM1662,...) of a device 
or device definition which the user has 
specified for his device reservatio 
(T800, T1800,...) 


Defines the type of volume Label for a 
voLume (cf. SVL). 
The following values are possible: 


STD: The voLume has standard 
Labels; 

BS1000: The disk has BS1000 Labels; 

TAPE-MARK: The tape begins vith a tape 
mark; 

NON-STD: The Label has none of the 


three attributes Listed above. 


This field defines the mnemonic name 
of the device as specified during 
generation. 


Provides information on the job name of 
the job addressed or on the user ID under 
which the job runs. 


Specifies whether the operator wishes to 
be informed of the first time disks are 
reserved by the tasks (with the option 
of rejecting these reservation requests). 
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Keyword Used in 
command 


PHASE 
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Meaning of the output columns 


Meaning 


ONLINE: The volume is mounted but not 
reserved; 

PREMOUNT: The volume is reserved; a device 

| reservation exists for future 
use; 

MOUNT: The volume has already been 
reserved but still has to be 
secured by the operator; 

IN-USE: The volume is released for use 
(except when ACTION=CANCELLED 
is specified). 


Volume monitoring takes place for the 
statuses PREMOUNT and IN-USE (a volume 

is always monitored if a valid reservation 
exists for it). In such a case the 

voLume monitoring facility is responsible 
for the following functions: 


- it ensures allocation of a device for 
tapes in the PREMOUNT status; 

- it requests the operator to make a 
voLume available again when the volume 
is considered to be reserved but is 
currently not accessible (INOP); 

- it sees to it that a NO-DEVICE status 
is cancelled as soon as a device of 
the required device type is free; 

- it initiates automatic repositioning 
of tapes in the event of an operator 
error (e.g. if he dismounted the 
wrong tape device). 
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Meaning of the output coLumns 


Keyword Used in 
command 
POOL SH-DEV 
PRE-/IN-USE SH-DEV 
( INF-ZSUM) 
RES-BY -MN SH-DEV 
( INF=SUM) 
RES-BY-TYPE SH-DEV 


(INF-SUM) 


3-114 


Meaning 


Defines the availability of a device in 
respect to several systems. Three defini- 
tions are possible: 


1. POOL=NO: This device is only available 
from within the user's own 
system. Access to a volume 
mounted therein is not 
possible when attempted from 
another system. 


2. POOL=SH: As a rule, this device is 
generated for several systems. 
Its hardware supports 
parallel use of more than one 

system (device with mutti- 
processor connection). 

A disk which is mounted on 

a device with this generation 
feature is generally operated 
as a shareable private disk 
(**x-generation with UGEN). 


3. POOL=SW: As a rule, this device is 
generated for several 
systems (x-generation with 
UGEN). In the case of disk 
devices: 
the device Likewise has a 
multiprocessor connections 
however, in contrast to 
POOL=SH, a private disk 
mounted on this device is 
generally system-excLusive 
(no SPD operation). 

If a PPD is used, the private 
disks mounted on these 
devices are generally only 
avaiLabLe for read access. 


Specifies the number of devices of the 
defined type which are implicitly reserved 
by means of volumes of the corresponding 
phase. 


Specifies the number of devices of the 
type in question which were reserved by 
a user by means of SEC-RES UNIT-mn. 


Specifies how many free devices of the 
specified type are required to handle 
previousLy acknowledged reservation 
requests (SEC-RES TYPE=3465,NUMBER=2) 
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- Meaning of the output coLumns 


Keyword Used in Meaning 
command 


SYS-ALLOC SH-DISK Specifies the mode of operation for use 
(ΙΝΕΞΡΑΝ) of a private disk by the user's own 
system with regard to other systems when 
USE=DMS is specified. 
Possible operating modes: 
EXCLUSIVE: Other systems are prohibited 
from using the disk. 
SHAREABLE: Other systems may also access 
the disk (SPD operation). 
Synchronization vith the other 
Systems is performed vith 
respect to the use of files 
and storage space; 
C CataLog Locks are kept on 
disk. 
TSN Specifies the 4-digit task sequence 
number for generating a job. 
TYPE SH-DISK Defines the device type of the volume 


(ΙΝΕΞΡΑΒ) from which information is requested. 
Apart from a request on the part of the 
user (SECURE,FILE,...2), the device type 
specification may also depend on the 
following: 


1. OnLine event: 
As a result of an activation inter- 
ruption the volume is assigned to a 
device whose DEVICE-TYPE specification 
then determines the device type of the 
volume in the event of a vsn request. 


2. SET-DISK command: 
As a result of predefinition of the 
device type by means of this command, 
the type can be defined even before a 
voLume is reserved. 
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Meaning of the output columns 


Keyword Used in Meaning 
command 


USE SH-DISK Provides information: 
- on the operating mode of a mounted 
voLume; 


- on the resulting degree of monitoring; 

- on the extent of checks made vhen 
allocation is performed by the 
monitoring facilities. 

The following values are possible: 

DMS: The volume is reserved by one or 
more DMS applications. OnLy 
readable volumes are accepted 
for allocation, i.e.: 

- Disks with or without standard 
Labels can be processed, but 
they must be uniquely identi- 9 
fiable. 

The default task reservation mode 

for USE=DMS is task-shareable for 
private disks and task-excLusive 
for tapes. Each operator 

intervention during PHASE=IN-USE 

Leads to REMOUNT/RECOVER, and 

to repositioning in the case 

of tapes. It is ensured that 

only one volume with the same 

vsn is reserved for DMS usage 

mode. 

SPECIAL: The volume is reserved by a 
special application (privileged 
application, e.g. VOLIN, INIT, 
testing and diagnostic programs, 
FDDRL, etc.) The task and system 
reservation mode is EXCLUSIVE. 
Checks made during allocation 
(VOLIN,INIT) or monitoring 
functions such as repositioning 
or MOVE (online FDDRL controls 23 
this by itself) can be switched 
Off by means of the special 
appLication. No verification of 
vsn uniqueness takes place. 

WORK: The mounted tape is used as a 
work tape (it is made available 
to the DMS user for processing 
work files). 


3-116 UBO05-J-Z55-5-7500 


- Meaning of the output coLumns 


Keyword Used in Meaning 
command 


USER-ALLOCATION SH-DISK Specifies which reservation requests made 
(INF=PAR) by the user (task-shareable, task- 
SH-DISK-DEF exclusive) are permissible for a private 

disk for which USE=DMS has been specified. 


VOL-A In the case of current public disks, this 
field merely indicates whether the mounted 
disk is the SYSRES disk, a PAGING disk 
or a conventional disk on public without 
special attributes (PUBLIC). 

In the case of private volumes, it 
provides information on the voLume's 
reservation as made by a user: 


© PAGING: The disk is part of the reserved 

pubset and is used for paging. 

PUBLIC: The disk is part of the reserved 
pubset of the reserved system. 

SYSRES: Public disk of the home pubset, 
on which catalog TSOSCAT begins. 

FREE: At the moment no user is accessing 
the volume. 

EXCL: The private volume is exclusively 
assigned to a user job (for which 
period of time other users cannot 
work with it). 

SHARE: The private disk is already 
reserved by one or more jobs. 
Requests from further users are 


permitted. 
VSN SH-RES "Name" of a volume: i.e. the volume serial 
SH-DEV number defined when a volume is initial- 
SH-DISK ized (VOLIN, INIT). If the volume does 


not have a readable Label or if the 
request for the volume did not include a 
vsn, Synonyms may also be output. 


The following values are possible: 

<vsn>: The vsn of a volume defined with 
VOLIN or INIT; see the VOLUME 
operand of the FILE command in the 
"Control System Command Language" 
manuals 

*UNKNO: The volume has no BS2000 standard 
Label; 

*SCRAT: The request for the voLume did not 
incLude a vsn (e.g. in the case 
of tapes, a FILE command vithout 
a VOLUME operand). 


Table 3-1: Meaning of the output columns used for the SHOW commands 
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CATAL 


4 MACROS WITH CONMAND FUNCTIONS 


This chapter contains the formats of those macros which have command 
functions. 


Conventions relating to BS2000 macros can be found in Appendix A.1. 


CATAL PROCESS CATALOG ENTRY «TYPE S» 


" The CATAL macro creates or updates the catalog entry for a file, file 
C generation group or temporary file. 


Format 1 for files 


Operation Operands 


CATAL pathnameil ,filename2] 


NLEWI WRITE NO 
C,STATE= 10 ,ACCESS= lL,SHARE- ] 
ULPDATEJ READ YES 


t umpass- fac rorass=| h 
passvordi passvord2 
Á 
B 
",εχρατο-| lat, nereo-aaysit backup Crd 
passvord3 D 
: E 
e SUCC 
YES YES FAIL 
CsLARGE| fac,vestroy-| fac, avozt= J 
NO NO ALL 
NONE 
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CATAL 


Format 2 for file generation groups 


Operation Operands 
CATAL pathnameil ,filename2] 
t/STATE| 


με,λοοεοο-| 
ULPDATEJ 


WRITE NQ 
]L,SHARE- 1 
YES 


NONE NONE 
C,RDPASS= JL,WRPASS- J 
passvord1 password2 


L ,RETPDzdayslLl,GEN-2max]l 


CYCLE 
REUSE 


C,DISP= 


DELETE 


KEEP 


lat, rinsronà 


A 
B 
L,DEVICE-2devicelL,VOLUME-vsnlL ,BACKUPz1C[J 
D 
E 


YES FAIL 
ΓΙ. ΑΒΟΕΞ JL,DESTROY- JL ,AUDIT-z ] 
NO ALL 
NONE 
For a description of the operands see the CATALOG command. 
Programming note: 
Register 15 is set to O upon successful compLetion of this macro. The error - 
codes for unsuccessful execution are specified in the IDEMS macro (Appendix 
Ae 3). 
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- CHNGE 


CHNGE MODIFY TFT ENTRY «TYPE 5» 


The CHNGE macro changes the file Link name of an entry in the Task Five 
Table. ALL other TFT entries remain unaffected. 
Operation Operands 


CHNGE CLink1] ,Link2 
For a description of the operands see the CHANGE command. 


Programming notes: 


© - The CHNGE macro is meaningful only for a TFT entry which was previously 
created by means of the FILE command/macro (not with OPEN). 


The reason for this is the different handling of the TFT entry when the 
file is reopened (see section 5.1, "Opening Files"). 


- The following return codes are set in register 15: 
00 - request successfully completed. 


The error codes for unsuccessful execution are specified in the IDEMS 
macro (Appendix A.3). 
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COPY 


COPY COPY FILE «TYPE 5» 


The COPY macro copies files, file generations, file generation groups or 
temporary files without modifying them. 


Operation Operands 


REPLACE 
COPY pathnamel,pathname2L[ , SAME] CWRITE= J 
NEW 


For a description of the operands see the COPY command. 


Programming note: 
The following return codes are set in general register 15: 
00 - request successfully completed. 


The error codes for unsuccessful execution are specified in the IDEMS 
macro (Appendix A.3). 


To avoid a collision with the AssembLer statement "COPY", the following 
command must be issued prior to the COPY macro: 


COPY OPSYN 
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DSTATUS 


DSTATUS OUTPUT DATA ON PERIPHERAL CONFIGURATION «TYPE S» 


The DSTATUS macro permits access to data provided by the information 
service facility (NKD) of the Nucleus Device Management (NDM). The data 
provides information on: 


- the resources occupied by a task; 


- the reservation and availability status of resources for devices, device 
types, disks or tapes; 


- the structure of the configuration; 


- the device queue. 


e The DSTATUS macro offers two separate basic functions: 
Function 1: Writing of output records. 


Output records contain information on the reservation and 
availability status of the specified devices, hardware units, 
resources, or of the overall configuration. The records are 
entered in an area of class 6 memory. This output area is 
comprised of an output control record and the relevant output 
records. The start address of the area is transferred in 
register R1. 

The user issuing the macro is responsibLe for returning the 
storage area (RELM). The Length specifications are to be taken 
from the output control area. When returning the storage area, 
care must be taken to ensure that: 


- the start address of the output buffer is aligned on the 
page boundary 
- the Length is converted from bytes to pages. 
Function 2: Generation of a DSECT for output records. 
With the aid of the symbolic name of the DSECT, the user can 
© access the contents of output records or obtain information on 
the structure of output records. 
The following restrictions apply to non-privileged users: 
- Task records are only output for tasks under the user's own ID 


- The user does not obtain any information on device queues. 


- Information pertaining to devices, disks and tapes is output only if the 
calling task has the appropriate resources at its disposal. 
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DSTATUS 


Macro formats and operand descriptions 


Function 1: Writing of output records 
Macro Operands 
OWN 
DSTATUS ΓΤΑΞΚΞ/{ addr [1 
(r) 
ALL 
[ ,DEVICE- FC addr J 
ΤΕ ) 
MN (r) 


MONITORED 
SCHEDULED 


[o] eri pyesi 
( 5 1 ) 


MN} (r) S 


[,DISC- 


ALL 
CPU 
IOC 
CHN 
CTL 
L,CONFIG-jDVC J 


tet | ben. [| 
( 8 ” ) 
του (r) S 


YES 
[ ¿GLOBAL = 1 
ΝΟ 


ie E. 
C,DVQ= J 
NO 
ALL 
C,SUMMARY= [^ ba ] 
( Ρ } 
ΤΝ (r) 
L 
(E,addr) 
C,MF= 1 


(E,(r)) 
DL ,PREFLX=p] 


Notes! 


- At Least one of the operands must be specified. 
- In the case of "MF=D,PREFIX=p" all further operands are ignored. 9 
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TASK= 


=OWN 


=addr 
=(r) 


DEVICE= 


{ooo} 


DSTATUS 


For all devices, disks and tapes of the specified task a 
task output record is written. The record contains inform- 
ation pertaining to devices, disks and tapes which have 
been reserved by the task. 


Specifications refer to the task making the call. 


"addr" is the symbolic name (address) of a field (word) 
along with the TSN (task sequence number) for a task. 


"r" is the register with the address value of "addr". 


A device output record is written for each device specified. 
ALL: ALL devices. 


FC: The entries in the subsequent List contain the code 
for device families (family code). 


TT: The entries in the subsequent List contain the code 
for device types (device type code). 


MN: The entries in the subsequent List contain mnemonic 
device names. 


"addr" is the symbolic name (address) of a field which 
contains either a List of mnemonic device names, codes for 
device families or device type codes and is to be aligned 
on the vord boundary. 


Format: 


- the first vord (right-justified) contains the number 
of subsequent entries in hexadecimal notation; 

- this is followed by entries, each of which is 2 bytes in 
Length and contains either the mnemonic device name or, 
Left-justified, the code for device families (family 
code) or the device type code. Surplus bytes are set 
to X'OQO'. ` 


"r" is the register with the address value of "addr". 
Example 1: 


2 device types with device type codes X'A9' (=D3465) 
and X'91*' (=FD3170) j 


e. 
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DSTATUS 


DISC= 


doce} 


Example 2: 


2 device families with family codes X'AQ' (= disk devices) 
and X*°90" (= floppy disks) 


inel 


For each specified disk (disk device), a disk output record 
is written. 


MONITORED: ALL disks for which a mount or monitoring job 
exists. 


SCHEDULED: ALL disks for which explicit user specifications 
vere made using the SET-DISC-PARAMETER command. 


VSN: The entries in the subsequent List contain the vsn's 
(Yolume Serial Number) of the disks. 


MN: The entries in the subsequent List contain mnemonic 
device names. 3 s 


"addr" is the symbolic name (address) of the field which 
contains a List of vsn's or mn's and is aligned on vord 
boundary. 


Format: 


- The first vord (right-justified) contains the number 
of subsequent entries in hexadecimal notation 

- This is followed by entries, each of which is 8 bytes in 
Length. They contain (Left-justified) either vsn's or 
mn's. Surplus bytes are set to X'OO'. 


"r" is the register with the address value of "addr". 

L: Information is output using the Long format. 

S: Information is output using the short format. 

TASKS: Output of a List with the TSNs of the tasks 
currently working with the disk. The List consists 


of 4-byte entries and is only output for private 
disks for which USE=DMS has been specified. 
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- DSTATUS 


CONFIG- | A CONFIG output record is written for each specified unit 
of the configuration. 


Note: 


In the case of Large configurations, the resulting output 
area may be extremely Large when CONFIG=ALL is specified. 


Pe ALL: ALL units of the configuration 
CPU: ALL central processing units 
roc: ALL input/output processors 
CHN: ALL channels 
CTL: ALL muLti-device controllers 
e | DYC: ALL devices 


MN: The entries in the subsequent List contain mnemonic 
device names. 


ICUU: The entries in the subsequent List contain device 
addresses (where device address is the path defini- 
tion for a device). The device address is 2 bytes in 
Length and is structured as follows: 


= ist half-byte 
- 2nd half=-byte 
- 2nd byte 


number of the I/O processor 
channel number 

connection number of multi-device 
controller and connection number 
of the device (if connected to 
the channel directly). 


"addr" is the symbolic name (address) of a field which 
contains a List of entries and is aligned on word boundary. 


Format: 
© - The first word (right-justified) contains the number 
of entries in hexadecimal notation 


- This is followed by entries, each of which is 4 bytes 
in Length and contains, Left-justified, either mn's or 
ICUUS. Surplus bytes are set to X'OO'. 

"r" is the register with the address value of "addr". 

L: Information is output using the Long format. 


S: Information is output using the short format. 


GLOBAL = This specifies that the setting of all global NDM controL 
parameters is to be output. 
=YES The output record is written. 
=NO The output record is not written (default value). 
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DSTATUS 


DVQ= 


=YES 


=NO 


SUMMARY = 


L 


(E addr) 


(E,(r)) 


DL ,PREFIX-pJ 


4-10 


This specifies that information pertaining to the device 
queue is to be output. 


DVQ output records are written. 
No DVQ output records are written (default value). 
Note: 


The DVQ operand may only be issued by the system administra- 
tor (TSOS). 


A SUMMARY output record is written for each specified device 
family (device type). It contains information on the device 
family or device type. For each device family, the number 

of SUMMARY records of its device types is provided. 


FR: The entries in the subsequent List contain the code for 
device families (family code). 

TR: The entries in the subsequent List contain the code for 
device types (device type code). 


"addr" is the symbolic name (address) of a field which 
contains a List of entries and is aligned on word boundary. 


Format: 

- The first vord (right-justified) contains the number of 
entries in hexadecimal notation 

- This is followed by entries, each of which is 2 bytes in 
Length and contains, Left-justified, the family code or 
device type code. 

"p^ is the register with the address value of "addr". 

This defines the macro format (cf. section 2.3.2). 


L-form; an operand List is generated. 


E-form; "addr" is the symbolic name (address) of the field 
with the operand portion. 


E-form; "r" is the register with the address value of "addr". 
D-form; a DSECT for the operand List is generated. 


"p" is the character that prefixes all symboLic names 
occurring in the DSECT; default value: p = N. 
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© DSTATUS 


Function 2: Generation of DSECTs for output records 


Operation Operands 


DSTATUS HEADER 
TASK 
DEVICE 
TAPE 
DISC 

RECORD= 

CONFIG 
GLOBAL 
DVQ 
SUMMARY 
ALL 


6 RECORD=HEADER DSECT for the output control record. 
The output control record contains: 


- pointers to the various output records 

- counters 

- Length specifications (Length of the output area, 
Length of the individual output records) 

- return codes for the various output records and 

- equations for the global return code (register R15). 


The Layout is reproduced on the foLLoving page. 


=TASK DSECT for the task output record (TASK operand in the macro 
for function 1). 


=DEVICE DSECT for the device output record (DEVICE operand) 


=TAPE DSECT for the tape output record (TAPE operand). 
=DISC DSECT for the disk output record (DISC operand). 
C -CONFIG DSECT for the CONFIG output record (CONFIG operand). 


=GLOBAL DSECT for the GLOBAL output record (GLOBAL operand). 
=DVQ DSECT for the DVQ@ output record (DVQ operand). 
=SUMMARY DSECT for the SUMMARY output record (SUMMARY operand). 
=ALL ALL DSECTs (RECORD=HEADER to RECORD=SUMMARY). | 


For the Layout of the DSECTs for the output control record (RECORD=HEADER) 
see the "Executive Macros" manual. | 


UB05-J-Z55-5-7600 | 4-11 


DSTATUS 


Return codes and error display 


After the DSTATUS macro is called (function 1), register R1 contains the 
address of the output area. 


The return codes for the various output records are shown in the output 
control records. For an explanation of the return codes see DSECT, output 
control record. 


A (global) return code pertaining to the execution 
R15: of the DSTATUS macro is transferred in the two 


GLobalL 
Return code 


X*ooo0" 
X*O004" 
X*'0008' 


Χ" 0108" 


X'0208" 
X' 0308" 


Note: 


rightmost bytes of register R15. 


ExpLanation 


Normal execution. Information complete. 

System error; output area not created. 

Macro executed incompletely (output records incomplete or 
missing). | 

Online data for disks currently not available. 

Online data for tapes currently not available. 

OnLine data for disks and tapes currently not available. 


In the case of return codes X'0108', X*0208", X'0308' repeat the catu 
(monitoring task in vait state). 


4712 
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ERASE 


ERASE ERASE FILE «TYPE 5; 


The ERASE macro is used to make a file (or file generation, file generation 
group or temporary file) Logically empty, deallocate the storage space 
assigned to a file and/or remove the file entry from the catalog. The macro 
processes partially qualified file names. 


Operation Operands 
ERASE pathname 
* DESTROY 
*SYSOUT DATA ALFTERJ 
E T h 
*SYSLST SPACE BLEFORE]J 
*SYSLSTnn CATALOG 


e *SYSOPT 


C,VOLUME=vsn] 
For a description of the operands see the ERASE command. 


Programming notes: 


- Register 15 is set to O upon successful completion of the macro. The 
error codes for unsuccessful execution are specified in the IDEMS macro 
(Appendix A.3). 


- If a partially qualified file name is specified, and one or more of the 
files cannot be erased (e.g. due to ACCESS=READ), the user receives error 
code X*O6D6" and erasure continues. 


- If *SYSOUT is specified during interactive operation, return code OSDF 


is placed in register 15. If the EAM file to be erased (*SYSLST, *SYSOPT) 
does not exist or is empty, no return code is given. 
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FILE J 


FILE DEFINE FILE ATTRIBUTES «TYPE S> 


The FILE macro is used to define files (or file generations or temporary 
files) and their attributes. With the exception of EAM files, all files 
must first be defined by this macro (or the FILE command). The file is 
thereby cataloged and the specified attributes remain known to the 
system. There is therefore no need to repeat these attributes in a FILE 
macro when the file is to be referenced again. 

Principal functions.of the FILE macro: 

- Catalog a new file or file generation (see the "filename" operand). 


- Generate an entry in the Task File Table (see the LINK operand and 
Fig. FILE-1 in the FILE command). 


- Request devices and volumes (see the DEVICE, VOLUME and TSN operands). ω 


- Cause console messages requesting the mounting of private volumes (see 
the MOUNT operand). 


- Allocate and deallocate storage space on disks (see the SPACE operand). 


- Allow processing of non-cataloged files or file generations on private 
volumes (see the STATE=FOREIGN operand). 


- Provide information regarding data organization on tapes (see the LABEL, 
TPMARK and CODE operands). 


- Define a file retention period (see the RETPD operand). 
- Specify the "open mode" (see the OPEN operand). 


- Specify the data structure for the various access methods: 


Operands Access method: 
SAM ISAM 


"U 
> 
= 


FCBTYPE 
RECFORM 
RECSIZE 
BLKSIZE 
SHARUPD 
KEYLEN 
KEYPOS 
DUPEKY 
LOGLEN 
VALLEN 
VALPROP 
OVERLAP 
PAD 
WROUT 


X X X x 


X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 
X 


p. μ.μ. μ- μ.μ. μ.μ: μ. >< μ- μ.μ. X 


i: ignored but not rejected, since in certain cases ISAM or SAM files 
can be accessed vith PAM. 


- Request private devices, volumes and storage space for the file data 
section of ISAM files if this is to be separated from the file index 
section (see the DDEVICE, DVOLUME and DSPACE operands). 
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Operation Operands 
FILE pathname 
L JL,LINK-ULinklL ,DEVICE-ddevicel 
*DUMMY 
PRIVATE | 
(PRIVATE,number) 
C,VOLUME= 
vsn } 
(VSN, cece) 
primary 


C,SPACE= imi cade | JL,STATE-FOREIGNJ 
( ) 


firstpage,amount,ABS 


INPUT 

OUTPUT 

EXTEND ISAM 
[ ,RETPD=days][ , OPEN=} REVERSE ΠΕΣ | 

UPDATE PAM 

OUTIN 

INOUT 


[ ,RECFORM= J0,RECSIZE=reclength] 
$ N 
ΕΕ) C,4AtI) 
U M 


STD NO 
[L,BLKSIZE-s ;(STD,integer) [1L ,SHARUPD- ] 
bufferLength YES 


C,KEYPOS=dispLacement][,KEYLEN=keyLength] 


e C,DUPEKY=YESI[C ,LOGLEN-7fLag11 


t NALLEN=FLag2]C,VALPROP=| ac overtar=ves: 


MAX 


YES 
t, PA-percentit uRouT=] Jat ppevzce-ddevice: 


NO 
vsn 
t ovoLune-l h 


CvSNpece ) 


primary 
C,DSPACE=j primaryLl ,secondary] ) ] 
(firstpage,amount,ABS) 
YES 
[ ,WRCHK- J 


NO 


© For a description of the operands see the FILE command. 
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FSTAT REQUEST CATALOG INFORMATION «TYPE 5» 


The FSTAT macro transfers either a List of file names or a List of catalog 
entries (partially or in their entirety, but without file security passwords) 
to the output area. 


Specification of a temporary file is possible. 
Format 1 


Operation Operands 
FSTAT inue ce omm | 


(C:catid: ] ($userid. ] [filename] ,ἰθη) 


area Length 
7i1‘S,area)t , 
(regi) (reg2) 


FNAM 
C>] SHORT [1 
LONG 


s YERSION=800 
C,PREFIX=id] [,ERR=(reg4)] 


RLEADJ 
C,ALCCESS] = 1 
WLRITEJ 


moou-o 


C,BACKUP= ] - 


^^ 


othe 


(date ,) 


A 
B 
C 
D 
E 
date 
L ,CREDATEJ 
(,date ) 
(date,date) 
date 
(date,) 


li 
t 


[ ,EXLDATEJ 
( ,date) 
(date,date) 
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C,EXTCENTS] 


C,FCBL TYPE] 


C,FSIZE = 


C,FROM = | 
C ,LALDATEJ 
L,PASS = 
C,SAVE = | 
L,SHLAREJ 
C,SIZE = 
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value 
(vaLue,) 


(,value) 
(value, value) 


PCAM] 
SCAM] 


ICSAM] 
NLONE]J 


PCAM] 
SCAM] 
( seso) 
ICSAMJ 
NC ONEJ 


SIZE 

value 

( vaLue,) ] 
(,value) 
(vaLue,vaLue) 


CATLALOGJ | 
1 
(vsn,device) 


date 

(date, 
= J 

(,date) 

(date,date) 


RLDPASS] 
WLRPASS] 


ELXPASSJ 
NLONEJ 


RLDPASS]J 
WLRPASSI 

( TITO 
ECXPASS] 
NLONEJ 


"κα 
1 
NCO] 

YCESJ 
= ] 

NCO] 
FCREEJSIZE 
value 
(vaLlue,) J 


( ,vaLue) 
(vaLue,vaLue) 


li 
(=) 
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FSTAT 


Operation Operands 
NCOJ 
C,SORT = 1 
ELILEJNAM 
NOCLOS 
C STATE 1 
PCLOSE 
PUBCLIC] 
L,SUPLPORTJ] = jPRDLISC] 1 
(PUBLLIC] ,PRDLISCI) 
YLESJ 
[GEN = ] 
NCO] 
[,TYPE = FGG] -Ἔ 
YLESJ 
[,VTOC = ] 
Νίο] 
catid | This operand denotes the identifier of the catalog from 


which the file or files are to be selected. 
Default value: default catalog ID of the appropriate user ID. 


userid This operand specifies a user identification. "$userid" 
designates all the user's files. If another user's 
identification is specified, only information concerning 
shareable files (SHARE=YES) is output. 
Default value: the user's own user ID, i.e. the one used 
in the LOGON command. 


filename This operand specifies the file(s) for which information 
on the status is to be provided. This may be a partially 
qualified or fully qualified file name, the name of a file 
generation, or the partially or fully qualified name of a 9 
file generation group. The maximum Length of the file name 
is 80 characters. Temporary files are supported; only the 
files of the user's own task are taken into account. 


Len For the "catid", “userid” and "filename" operands a field 
of the Length "Len" is generated; this field contains the 
file name (Left-justified) and is padded with blanks. 

If this operand is not specified, a field with the required 
Length is reserved. 

Both the "catid" and "filename" operands can be used 

in accordance vith the patterns that have been defined 

(see the FSTATUS command). 
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area This specifies the symbolic address of the output area to 
which the output List is to be transferred. 


(S,area) This operand specifies the symbolic address of the output 
area; this is not an absolute address but may be addressed 
via a base register (e.g. in a dynamic main memory with a 
DSECT overlay). 


(reg1) This specifies the register containing the address of the 
output area. 


Length This operand specifies the output area Length. 
Minimum Length: 9 
Default value: 60 bytes when SHORT is specified, 
2048 bytes when LONG is specified. | 
If the specified Length is insufficient, no information 
is transferred. 


© (reg2) This is the register containing the output area Length. 
FNAM A List of file names is to be transferred to the ouptut 
area. 
SHORT The static portion of the catalog entry (60 bytes) and the 


file name (maximum of 54 bytes) are transferred to the 
output area. These parts of the catalog entry can be given 
a symbolic name with the IDCE macro. 


LONG The complete catalog entry is output (the bytes for the 


file passwords are set to binary 0; for exceptions see 
"PASSWORD"). 


The catalog entry is made up of the following parts: 


4. Static part 
es File name 
Su Extension 


6.8 Volume table, vsn table (only for catalog entries 
which define files) 
4. Ὁ FGG option (onLy for group entries for file generation 


© groups) 


The following macros exist for the provision of symbolic 


names: 
1. IDCE (catalog entry) 

2. None 

3. IDCEX (catalog entry extension) 


6. 8 IDVT, IDEE (volume table, extent List) 
6. Ὁ IDCEG (catalog option for FGG) 


PREFIX=id Identifier for distinguishing between several calls of 
: the FSTAT macro in one program section. One to three 
characters are permitted for the identifier, the first of 
which must be a Letter. 


ERR=(reg4) Register for accommodating additional error information 
(besides register 15). 


VERSION=800 The macro for Version 8.0 is called If this operand 
is omitted, the macro for the earlier version is called Ν 
(see format 2). 
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Note: 

For "regi", "reg2" and "reg4" the values 1 and 15 are prohibited, while 1 
must not be specified for "reg3". 

The specifications must be pairwise disjoint (AND/OR Logic). 

For a description of the remaining operands see the /FSTATUS command. 


Specification of the output area 


‘The following paragraphs describe the output format generated by 
the FSTAT macro. 


Information concerning files in various catalogs or under various user IDs 
can be transferred to the output area vith the FSTAT macro by specifying 
patterns in the PVSID or in the user ID. This information is not contained 
in the catalog entry and must therefore be additionally transferred to the 
output area. 


In this new version of the FSTAT macro, the structure of the output area 
is as follows: 


cena | PREFIX 


LEN4 PREFIX Data EOL4 


where 
ANZ: is the total number of files affected by the FSTAT macro 
(4 bytes) 
LENG: is the Length of the subsequent PREFIX and subsequent data + 4 
(4 bytes) 
PREFIX: 
LP: Length of PREFIX (2 bytes) 
LC: Length of "catid" + 2 (2 bytes) 
catid: Catalog identifier for all entries in the subsequent data 
section 
LU: Length of the "userid" * 2 (2 bytes) 


userid: User ID for all entries in the subsequent data section 
EOL4: End-of-List identifier (X'QOO000000"') 
RET: X'oo' ALL requested information is transferred to the output area. 


X'O1"' OnLy incompLete information is transferred to the output 
area after a request. 
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Note:! 


If no files have been affected by the macro, the output area is structured 
as follows: 


| ANZ | EOL4 (Length: 9 bytes) 


In turn, each "data section" comprises a List. The "user information" 
fields within this List contain the information which the user has actually 


requested. 


6 eeeee user information Eg 


where 


user information eee. 


LEN2: Length of the subsequent user information + 2 (2 bytes) 
EOL2: End-of-List identifier (xX*"0000*) 


User information is dependent upon the input operand FNAM, SHORT or 
LONG and is composed of: 


FNAM: File name 


The maximum Length of this user information is 41 bytes. 


SHORT: 
static portion CE 


The Length of the static portion of the catalog entry is 60 bytes. 
The Last byte contains the Length of the file name which follows. 


'- The maximum Length of this user information is 101 bytes. 
LONG: CompLete cataLog entry (cf. section 1.2) 


The maximum Length of this user information is 2032 bytes. 


Error recovery 


Return codes are stored in register 15 and in a second register (ERR 
operand) for purposes of error recovery. 


The following return codes are transferred in register 15: 
X'O0000000' Request successfully compLeted. 


otherwise DMS error code in the event of unsuccessful completion 
(see the IDEMS macro). 
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In addition, the following return codes are stored in the 


by the ERR operand. 


Byte3 Byte2 Byte1 ByteO 


ByteO: 


Byte1l: 


Byte2 and byte3: 
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X*OO" 
X'01"' 


register specified 


Required information transferred completely to output area. 
Only part of required information transferred to output area. 


More exact specification for DMS error "O06B8" in register 15 


X' OO" 
X'0^4" 
X'08'" 
X'Qc' 
X'10' 
X'14' 
X'18* 
X'1c* 
Χ' ΖΩ" 
X"24!" 
X*28" 
X*'2C" 
X'30' 
X" 34" 
X' 38" 
X' 3C" 
X' 60" 
X' 44" 
X'48' 
X' 4C" 
X' 50" 
X' 56" 
X' S58" 


DMS error "06B8" did not occur 
Invalid operand 


Error 
Error 
Error 
Error 
Error 
Error 
Error 
Error 
Error 
Error 
Error 
Error 


in 
in 
in 
in 
in 
in 
in 
in 
in 
in 
in 
in 


Not used 
Not used 


Error 
Error 
Error 
Error 
Error 
Error 


in 
in 
in 
in 
in 
in 


the 
the 
the 
the 
the 
the 
the 
the 
the 
the 
the 
the 


GEN operand 
TYPE operand 
STATE operand 
VTOC operand 
SUPPORT operand 
VOLUME operand 
FCBTYPE operand 
ACCESS operand 
SHARE operand 
PASS operand 
BACKUP operand 
XXDATE operand (CRDATE,EXDATE,LADATE) 


at present > 
at present 


the 
the 
the 
the 
the 
the 


FROM operand 


FSIZE operand 

SIZE operand 

SAVE operand 

EXTENTS operand 

FROM operand 

SORT operand 

together with VOLUME, SUPPORT on VTOC operand 


Not used at present (constant X'00") 
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Operation 


FSTAT 


FSTAT 


Operands 

SHORT 
[pathnamel,area,LULengthlL, 

LONG 


YES 
teenz] lat, rvee-ree1 t, sTaTe=nocLos3 


NO 


PUBLIC YLES] 
[ ,SUPPORT= JC, VOLUME=vsn][,VTOC= 1 
ΝΕΟΙ 


PRDISC 


guseris.ffitenane} | 


“pathname” stands for: [suseráa. C#itenane! 


catid 


userid 


filename 


area 


Length 


filename 
This operand specifies a catalog identifier. 


This operand specifies a user ID. The specification "Suserid." 
refers to all files belonging to a user. If the ID of any 
other user is specified, only information on shareable 

files (SHARE=YES) is output. 

Default value: the user's own ID. 


This operand specifies a fully or partially qualified file 
name. In the following instances merely a List of file 
names is transferred to the user area: 

- when a partially qualified file name is specified; 


- when a fully qualified name for a file generation group 
is specified in conjunction with GEN-YES. 


The symbolic address of the user area to which the catalog 
entry or the List of names is to be transferred. 


This specifies the Length of the user area. 
Default values: 


60 bytes when SHORT is specified, and 
2048 bytes when LONG is specified. 


If the specified Length is insufficient, no information is 
transferred. 


The static portion of the catalog entry (60 bytes) is 
transferred to the user area (see “filename” for 
exceptions). This part of the catalog entry can be given 
a symbolic name using the IDCE macro. 
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LONG The complete catalog entry is output (the bytes provided 
for passwords are set to binary 0). 


The catalog entry consists of the following parts: 


1. Static part 

2. File name 

3. Extension 

6.8 Volume table, vsn table (only for catalog entries 
which define files) 

4.b FGG option (only for group entries for file generation 
groups) 


The following macros exist for the provision 9f synbotic 


names: 
a, IDCE 
2 None 
3 IDCEX 
42a IDVT,IDEE ΜΝ 
«Ὁ IDCEG 

GEN=YES If the specified file name refers to one (or more) file 


generation groups, this operand results in output of the 

group name, followed by all generation names. These names 

are not sorted. 

Each name is preceded by a 1-byte Length field containing à 
the value "name Length + 1". 


ΞΝΟ Νο information concerning file generations is requested. 
TYPE=FGG These operands are meaningful only if the specified file 
STATE=NOCLOS name is partially qualified or refers to a file generation 


SUPPORT=PUB[LIC] group. Specification of one of these operands results in a 

SUPPORT=PRD[ISC] selection being made from all catalog entries referenced 
by the file name, followed by output of the associated 
names (cf. Notes). 


VOLUME=vsn This operand outputs all file names or catalog entries of 
; files which occupy space on the specified volume. 


VTOCZYLESJ This operand outputs the VTOC catalog entries (from the 
F1 Label of a private disk) on the basis of the Last 
current status in the entire computer network. 
This entry causes all other keyword operands to be ignored. 


-[NOJ This operand outputs the TSOS catalog entries on the 
basis of the Last current status in an individual co-user. 
(Co-user: CPU for which a random access device vas defined 
as shareable. ) 


Programming notes: 


= Selection of the catalog entries takes place when the following operands 
are specified: 


TYPE=FGG Selection is on the basis of the catalog entries of file 


generation groups. However, the names of the generations 
of an FGG are only output if GEN=YES is specified as well. 
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STATE=NOCLOS Selection is on the basis of the catalog entries of files 
| which are not closed. In this case selection also covers the 
generations of an FGG. GEN=YES need not be specified. 


SUPPORT= Selection is on the basis of the catalog entries of files 
and file generation groups on 


- public volumes (=PUBLIC) 


- private disks (=PRDISC) 


- If a combination of the TYPE, STATE and SUPPORT operands is specified, 
the catalog entries satisfying all of the conditions are selected. 


- If a fully qualified file name is specified, the catalog entry (SHORT 
or LONG) for this file name is transferred to the specified area. The 
passvord fields are set to binary zero: 


e - A name List with the following format is output: 


Length of the file name File name (up to 

* 1 (1 byte ) 41 bytes) 
End of List Output compLete (1 byte)? 
(1 byte, X'OO"') yes (X'00'), no (Χ7017) 


The name of a group entry is followed by the character string ".(FGG)". 
The Length field has the value: Length of the group name + 7. 


The List ends with a byte containing the value X*'OO'. 


A further byte indicates whether the user area was Large enough to 
accommodate all the file names. 


where: 
G Χ 0Ο ALL the file names have been transferred to the user area. 


Χ ΩΙ" One or more file names could not be transferred to the user area 
as it vas already full. 


- The following return codes are set in register 15: 
00 The request was successfully completed. 
The error code for unsuccessful termination is defined in the IDEMS 


macroe 


Example: 


06 KLAUS OB ABRECHNUNG | ου | o0 ( ABRECHNUNG = payroLl) 
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IMPORT CREATE CATALOG ENTRY FOR PRIVATE FILES «TYPE S» 


The IMPORT macro catalogs files contained on a private disk (see the 
IMPORT command). 


Operation Operands 
IMPORT [pathname] , VOLUME=vsn,DEVICE=device 


YES 
„AREA= Cadar Length) t, REPLACE=Í 4551 
NO 


YES YES 
C,GEN= lL,LIST-(1NO [1 
NO ONLY 


C,PVSID=catid] 


AREA=(Caddr,Llength) 
"addr" is the symbolic address of a user area to which the 
output information is to be transferred. "Length" specifies 
the Length of the user area. If the operand LIST=NO is 
specified, this entry can be omitted. 


For a description of the remaining operands see the IMPORT command. 


Programming notes: 


- Each item of information transferred to the user area is 56 bytes Long 


and has the following format: 
pathname (54 bytes) Coded return information 
(2 bytes) 


- The coded return information has the following meaning: 


Leftmost byte: This byte is significant only if the macro is used by 
the system administrator. 


Rightmost byte: 

c'o’ The file has been newly cataloged. 

eair Ὧν A file already cataloged with this name has been erased. 
If the operand LIST-ONLY was specified, this value simply 
means that a file with this name already exists. The 


protection attributes are not checked in this case. 


c*2" A file with this name already exists and the operand 
REPLACE has the value NO. 


c*3s°* The already cataloged file is protected (error when erasing 
this file). 
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C'4" System error when reading the catalog. 

c's’ A catalog entry for this file on the private disk already 
exists. 

C'e' System error when reading the F1 Label of the private 
disk. 

ο.» The file is a file generation whose absolute generation 


number is not compatible with that which already exists 
(generation number too high). 


ο ο Catalog entry already exists and was overwritten. 
ς"9" Catalog entry already exists and the file is Locked. 


If the value of the return information is equal to C'O', C'1', 0:15: or 
C'8', this indicates that a file on private disk has been successfully 


e processed. | 
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RDTFT OBTAIN INFORMATION FROM TFT AND TST «TYPE 5» 


3y means of the RDTFT macro, the user can cause status information from the 
TFT relating to the files and devices currently in use to be output to a 
user area. Furthermore, he can obtain information from the associated TST. 
Operation Operands 
RDTFT area 
,CLength] 
SHORT 
[ὦ 1 
LONG 2 
L,FILE-pathnamel 


C,LINK=Link] 


area This operand specifies the symbolic address of the user 
area to which the information from the TFT is to be 
transferred. 


Specification of the operand "area" is mandatory. 
Length This operand specifies the Length of the user area. 


Default value: 140 bytes if SHORT is specified, 
2048 bytes if LONG is specified. 


SHORT The static portion of the Task File Table, followed by the 
static portion of the associated TST, are transferred to 
the user area (i.e. without the device table). 


LONG The complete Task File Table (TFT), followed by the 
associated TST including the device table, are transferred 9 
to the user area. 


By means of the DMADR macro, the information output in 
response to LONG or SHORT can be provided with symbolic 
names, provided that the LINK operand was specified. 


Note: 


Positional operands: a comma must be entered for "Length" 
if SHORT or LONG is specified, but "Length" is not. 


FILE=pathname Only the file name and the associated Link name are 
transferred to the user area. 


In this case, the DMADR macro cannot be used for symbolic 
addressing. 
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"pathname" stands for: C:catid:J[$userid. ] filename 


catid This operand denotes the catalog identifier associated with 
the file. If this entry is missing, the default catalog ID 
assigned to the user ID is assumed. 


userid This operand denotes the user identification associated 
with the file. If this operand is omitted, the user's own 
user ID is assumed. 


filename This operand specifies the fully or partially qualified 
file name (up to 41 characters). If the file name specified 
does not begin with the user ID, it is prefixed by the 
user ID of the job. 
If "filename" designates a file generation of a group, the 
absolute value of the generation number must be specified. 
When temporary files are specified, the internal file name 
is output. 


© LINK=Link This operand specifies the file Link name. 

If the LINK operand is specified, only the information 
from the TFT (including the TST Linked with it) is 
transferred to the area. Otherwise the selection of 
the TFT is not dependent on the file Link name. 


Notes: 


- No TST information can be transferred to the user area unless the Task 
File Table (TFT) is Linked with a TSET. If it is not, the appropriate 
section within the user area is set to binary zero. 


- If the LINK operand has been specified, only status information relating 
to the TFT entries associated with the file Link name is transferred to 
the user area. 


= Output takes the following form, as indicated in the DMADR macro, 
providing the LINK operand has been specified: 


Length of the File Path name TST TST 
© path name + 8 Link (54 bytes)| static VoLume 
bytes * Length name portion information 


of the TST * 2 (8 bytes) for the LONG 
(2 bytes) operand 


- If the LINK operand was not used, or if a file Link name consisting of 
blanks was specified, a chronological List of file Link names and the 
file names associated with them is output, i.e. the file Link name of the 
TFT created Last is transferred first. 


- The List is terminated by a byte containing the value X'OQO'. A further 
byte indicates whether the user area was Large enough to accommodate all 
the file Link names and file names. 

Where: 


X'OO' ALL the file Link names and their file names have been 
transferred to the user area. 


X'O1" One or more file Link names, together with their file names, 
could not be transferred because the user area was already full. 
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- The following return codes are set in register 15: 
X"00" ~ request successfully completed. 


The error codes for unsuccessful execution are specified in the IDEMS 
macro (Appendix A.3). 
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REL DELETE TFT ENTRY «TYPE 5) 


The REL macro deletes an entry in the Task File Table. 


Operation Operands 4 


REL Clink] 


For a description of the operands see the RELEASE command. 
Programming note: 


Register 15 is set to zero upon successful compLetion of the macro. The 
error codes. for unsuccessful execution are specified in the IDEMS macro 


© (Appendix A.3). 


VERIF RESTORE FILE «TYPE S» 


The VERIF macro serves to restore corrupted files (see also section 2.1.7, 
"Restoration of Corrupted Files"). 


Operation Operands 

| YES 

VERIF pathnameliL,Lpathname21L,REPAIR-21NO [11 
ABS 


"pathnamel" stands for: [:catid:][$userid] filename1 
C "pathname2" stands for: [:catid:J[Suseridl]fivlename2 


fivename1 Fully qualified name of the file to be restored. 
For a description of the remaining operands see the VERIFY command. 


Programming note: 
Register 15 is set to 0 upon successful compLetion of the macro. The error 


codes for unsuccessful execution are specified in the IDEMS macro (Appendix 
A. 3). | 
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5 ACCESS TO FILES 


Each program that has to process a file must perform the following actions 
when it executes in a job: 


e Set up the file (using a FILE macro). 


This action is not required if the file is already cataloged and has been 
provided vith storage space. 


e Open the file (using an OPEN macro). 


e The system checks whether the calling job is authorized to access the 
file and prepares for the actual access to the contents of the file. 


e 9 Access the file contents (using access methods of the DMS). 


Upon request the system transfers data between the calling job and 
the five. 


e Close the file (using a CLOSE macro). 


The system Logically disconnects the calling job from the file, 
after which data transfer requests are rejected. 


A job can open a file, access its contents and close it as often as it 
Likes. 


It should be noted, however, that opening and closing a file are very 


time-consuming actions; consequently, a job should not open a file until it 
is able to process it, and close it only once processing is complete. 
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5.1 OPENTRG FILES 


5.1.1 General 


The OPEN macro serves to open a file. This macro associates the file to be 
opened with a File Control Block (FCB). 


The File Control Block therefore contains a file Link name, and optionally 
the file name. It also describes the file's technical characteristics, 85 
seen by the program. 


What information is required by the DMS for opening a file? 


The following points need to be clarified before the DMS is able to open a 
five: 


€ Which file is to be opened? 


e Does the calling job satisfy the conditions stipulated by the file's 
protection attributes? 


e With which access method is the file to be processed? How is the file 
organized (block size, record Length etc.)7? 


e Is the file to be opened as an input file or an output file? If it is 
to be opened as an output file, is it to be replaced or to receive 
further data? 


9 In which part of the address space are data buffers to be set up? 
In user memory (class 6) or in system memory (class 5)? 


9 How are the Logical records to be transferred to the job and received 
by the job? Is in each case the address at which the current Logical 
record begins in the buffer to be transferred (Locate mode), or is the 
record in a user area to be transferred (move mode)? 


9 Are other jobs permitted to access this file simultaneously (shared 
file update)? 


€ If the file is on private volumes or is to be created on private 
volumes: Which volumes should be used? 


e At which address is the program run to be continued in the event of an 
error or a contingency? 


From where does the DMS obtain the information required? 


The DMS obtains the answers to the above questions from the following 
sources: 


1. A FILE command containing the same file Link name as the program's 
File Control Block. (These details are kept internally in the Task 
File Table. ) 

2. The program's File Control Block, to which the OPEN macro refers. 


3j. The catalog entry for the specified file. (This means a file must 
always be cataloged before it can be opened. ) 
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4. When checking the access authorization, the DMS uses additional 
information originating from a PASSWORD command and which is stored 
internally in the job's password table or in the File Control Block 
(field ID1PASS). 


Se TO determine the open mode (input file, output file), the DMS uses, in 
addition to 1. and 2., an entry in the OPEN macro. (The entry in the 
OPEN macro has priority over those in 1. and 2.) 


The following applies to information contained in more than one of the 
sources 1. through 3.: 


e Information in the FILE command has priority over information in the 
File Control Block and the catalog entry. 


e Information in the File Control Block has priority over information 
in the catalog entry. 


e If information from 1. and 2. is incompatible with the contents of the 
catalog entry to the extent that the file cannot be processed, the DMS 
aborts opening vith an error code. 


Exception: 


The DMS always takes information concerning the retention period of an 
existing file directly from the catalog entry. 


5.1.2 File Control Block (FCB) 


An FCB can be created/modified in the following stages: 


1. Using the FCB macro when the program is written. This macro reserves 
storage space for the control block and optionally supplies information 
εδ, 


2. During program execution, prior to opening the file, by directly 
writing in current values. The IDFCB macro may be used to do this 
(see Appendix A.2). | 


3. While the file is being opened, the user is able to check and, if 
necessary, modify the File Control BLock after certain processing 
steps of the OPEN routine (see the EXLST macro, operands OPENX and 
OPENZ). 

Thereafter modifications to the FCB by the program are not 
permitted. 


Functions of the File Control Block during file processing 


As Long as a file remains open, the File Control Block contains all the 
information describing the current status of the file. 


This information is usually of significance to the user only after an 
error exit has been executed (see the FCB macro, operand EXIT= and the 
EXLST macro). 


In this case, the File Control Block also contains a DMS error code and 


an identifier for the error exit (see also section 5.3, “Handling Errors 
and Contingencies"). 
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5.1.3 Sequence of Events when Opening a File 


The DMS carries out the following activities when a disk file is opened: 


9 Complete the File Control Block from the FILE command and catalog 
entry sources. 


e Allocate buffer areas. 
e Request volumes (for files on private volumes). 


e Load access method routines; these routines carry out the blocking and 
debLocking of Logical records and are treated as a part of the user 
program. 


e Set up a P2 File Control Block (P2FCB); this is a control block used 
internally by the DMS and which cannot be accessed by the user. 


e Update the catalog entry (for output files). 


A detailed description of the sequence of events involved in opening disk 
files can be found in the following section. 


DetaiLed sequence of events in opening a fiLe 


1. Search the TFT (Task File Table) entries for the current file Link name 
(contained at this point in the File Control Block, and which either 
originates from an FCB macro or vas written directly into the control 
bLock). 


If the Link name is not found, a TFT entry is created. If the Link name 
is found, the FCB of the user is updated due to the TFT information, 
as the TFT contains FCB information provided by a previous FILE command. 


Notes! 


- If the LINK operand in the FCB has the value 8X'40' (8C'.*), the 
DMS reserves a new TFT entry without checking whether there already is 
a TFT entry with the value specified. This new TFT entry is marked 
as "active". The following fields are then transferred from the FCB to 9 
the TFT. , 


file Link name, 
file name, 
OPEN mode. 


- If there is no TFT entry with the specified LINK value, a new TFT 
entry is requested, marked as active, and the same fields are 
transferred to the TFT. 

At the time the CLOSE command is issued, such an entry is automati- 
cally released by the system. 


If a TFT entry is found, and this entry vas created by a FILE 
command, the following fields are transferred from the TFT to the 
File Control BLock: 


SHARUPD *KEYLEN *VALPROP 
filename PAD *LOGLEN 
RETPD *RECFORM *VALLEN 
*RECSIZE *FCBTYPE WROUT 
*BLKSIZE DUPEKY OPENmode 
*KEYPOS OVERLAP 


U805-J-Z55-5-7600 


- Opening fiLes 


Notes: 


- Only those fields specified in a previous FILE command are 
transferred. 


- Fields of the TFT entry which have the value O (i.e. the 
corresponding operand in the FILE command vas specified as a 
null operand) are not transferred to the File Control BLock; 
however, a bit is set in the corresponding field of the File 
Control Block. These fields are completed Later from catalog 
information (applicable only to the fields marked with an asterisk 
in the above List). See also 2. below. 


2. Seek and read the catalog entry for the file. Complete the undefined 
fields in the File Control Block using information from the catalog, 
if possible. 


Only those fields in the catalog entry which have null values are 

e transferred to the File Control BLock (see fields marked with an 
asterisk in 1. above). 

The vay in which the catalog is searched depends on how the file name 
was specified: 


- If the file name contains a user identifier (S$Suserid.), this user ID 
is used for the search. If no file is found under "sSuserid.", an 
error message with error code 0035 is issued. 


- If the file name is specified without any user ID, searching is 
performed using the user ID under which the job is executing. If no 
file is found under this user ID, the open formats differ, as 
described beLow: 


1. Standard case: Error message DMSOD33 is output. 


2. If the operand OPTION=GLODEF was specified in the FCB macro, the 
file is searched for under the ID which the system ; 
administrator stored in the cLass 2 option DEFLUID. If the five 
cannot be found under this ID either, the error message is 
Likewise 0D33. 


© Example: 


Defining 
DEFLUID :¥:$GLOB 
The job $USER identification 


Standard catalog identifier C 
Option=GLODEF set 


PVS 
Y 


PVS PVS 
A C 


$GLOB. HUGO SUSER. HUGO $GLOB. HUGO 
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Specification of| is the equivalent of] Result 


HUGO : C: SUSER. HUGO File found under default 
catalog ID 
$HUGO : Y: $GLOB. HUGO Catalog ID Y and user ID 


$GLOB are completed from the 
DEFLUID specification. The 
file is found on PVS Y. 


: C: HUGO : C: SUSER. HUGO File found on PVS C. 
: A: HUGO >A: $GLOB. HUGO Only the user ID $GLOB is 


completed. The file is found 
on PVS A. 


3. If the volume List for the TFT entry does not exist, it is created 
using information from the catalog, and the volumes are requested. 
If the volume List for the TFT entry already exists, i.e. if it vas 
created by a FILE command, but MOUNT-O was specified, then the 
volumes are requested. : 
Otherwise (MOUNT=0) a check is made as to whether the correct volumes 
vere made available. 


4. In the event of contingencies, a branch is made to the OPENX exit. 


5. If the OPEN operand has the value OUTPUT or OUTIN, the following fields 
are transferred from the File Control BLock to the catalog entry: 


FCBTYPE 
BLKSIZE 


If FCBTYPE + PAM: 


RECFORM 
RECSIZE 
KEYLEN 
KEYPOS 
VALPROP 
- VALLEN 
LOGLEN 


In the case of OPEN INPUT, IOAREA1 and IOAREA2 are already provided 
with data. 


6. If the OPEN operand has the value OUTPUT or OUTIN, the program receives 
control at the OPENZ exit, assuming this exit is provided for in the 
program. Modifications now made to the File Control BLock no Longer 
affect the catalog entry. 

7. Verify passwords. 


8. Allocate input/output buffers and validate buffer addresses, if 
necessary. 
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9. Establish connection with the access method. Load routines for 
blocking and debLocking Logical records (SAM, ISAM). 


10. Update the catalog entry if the file vas opened in OUTPUT or OUTIN 
mode. 


Warning: 


Technically speaking, a file does not exist until it has been opened once 
in OUTPUT or OUTIN mode, and then cLosed again. 
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5-2 CLOSING FILES 


Any file that has been opened must be closed with a CLOSE macro after 
processing. This may be done in the following ways: 


9 CLosing one file. 
The CLOSE macro designates the file to be closed via the File Control 
Block that was also used for opening the file. 


e Closing all the files that have been opened by the calling job at this 
time. 


The DMS carries out the following activities when a disk file is closed: 

- Release all the work areas occupied in cLass-5 memory during file 
processing (e.g. buffers allocated automatically when the file vas 
opened). ὃ 

- Update the catalog entry if necessary (for output files). 

At this point the following information is placed in the catalog entry: 

creation date, expiration date, and a pointer to the Last PAM block of 

the file. 

= Wait for compLetion of all outstanding write operations. 


- Unlock all PAM blocks still Locked in the file for the calling job. 


- Provide the FCB vith the contents it had before it vas opened. 
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5-3 HANDLING ERRORS AND CONTINGENCIES 


During the processing of a file, situations may arise that require a 
decision from the task, e.g. if end of file is reached during reading, or 
if an error occurs, or if conflicts with other jobs arise during shared 
file update. 


To enable the DMS to communicate with the user job in such situations, an 
exit address should be specified in the File Control Block (operand EXIT= in 
the FCB macro). 

If this address is not available, the DMS aborts program execution if errors 
or contingencies occur. 


The following options are available to the programmer for defining exit 
addresses for different classes of contingencies and errors: 


1. Specifying, in the operand EXIT= of the FCB macro, the address of a 
program section which is responsible for processing all errors which may 
occur. This address must be enclosed in parentheses, i.e. EXIT=(addr). 


The ID1XITB field of the File Control Block should then be examined in 
this program section to determine which event caused the exit. 


Depending on the type of event, it may also be necessary to examine the 
ID1ECB field to obtain an error code. 


See Appendix A.3 for further details. 


2. Specifying the address of an EXLST macro in the operand EXIT= of the 
FCB macro. This address should be specified without parentheses, i.e. 
EXIT-addr. 


For each type of event, the address of a program section responsibLe for 
processing this event should then be given in the EXLST macro. 


Processing continues as described under 1.; field IDAXITB need not be 
examined, however, if an event type corresponds exactly to the 
appropriate EXLST exit. (This applies to all EXLST exits except 
COMMON. ) 


3. Using technique 2. and specifying in the operand COMMON- of the EXLST 
macro the address of a program section responsible for several types 
of events. This program section should be constructed as described 
an 1. 


No matter which option is used, the following conventions apply: 


9 The DMS places the address of the File Control Block in general register 
1 before passing control to the user program. (In the case of multiple 
files, therefore, it is possible to use the same program sections for 
handling errors.) 


9 The DMS transfers to the IDIRTNAD field of the File Control BLock the 
address of the instruction which, during normal processing, would be 
processed next. This address refers either to the next instruction in the 
user program or, in the case of some action macros (e.g. PUT, GET), to 
the File Control BLock. 


9 The type of event is contained in coded form in the ID1XITB field of the 


File Control BLock. The various codes are Listed in Table 5-1. 
(See the EXLST macro.) 
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e In the case of the EXLST exits ERROPT, OPENX, OPENZ and WLRERR the 
program cannot be continued until the EXRTN macro is specified. 


e When a special status occurs during file processing, fields ID1XTB and 
IDLECB in the associated PiFCB are provided with the appropriate 
information by the system. These fields are not reset when processing 
is continued by the DMS, i.e. they are not updated until another special 
status occurs. ! 


Note: 

The DMS error codes are Listed using the IDEMS macro. 

Hovever, the texts describing the various errors are very brief. More 
detailed information can be obtained using the HELP command; here the 


Leading zero of the DMS error code should be replaced by DMSO. 


In the same vay the meanings of the error messages and the possible measures 
ito be taken errors occur can be found in the "System Messages" manual. 
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5-4 SERVICE MACROS FOR DISK FILES 


CLOSE CLOSE FILE «TYPE R> 


The CLOSE macro is used to disconnect a file from a user program. ALL I/O 


buffers previously automatically secured by the system are also released. 
The FCB is reset to the contents it had before the OPEN macro vas issued. 


Operatiori Operands 
CLOSE ALL 
| fcbaddr 
(1) 
ALL This operand specifies that all files for the job, except 


system files (e.g. SYSLST), are to be closed. User EAM 
files are not closed. If a file is closed abnormally, a 
varning message is issued. 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be closed (exit address). 


(1) Register 1 contains the FCB address. 
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EXLST CREATE BRANCH ADDRESS LIST «TYPE 0» 


The EXLST macro is used to convey to the DMS the addresses of program 
sections for handling errors and contingencies. 

The values of the individual operands are symbolic addresses of the 
associated program sections. NO indicates that the program does not wish to 
receive control if the relevant condition occurs. 

The default function of each operand is underlined To nullify the default 
value, it is necessary to specify the keyword with a null operand. 


Format for disk files 


Operation Operands 
EXLST relexp relexp 
C[CLOSER= 1 L,coMMON-revLexpl L,DLOCK- ] 
Νο | NO 
reLexp reLexp reLexp 
[ ,DUPEKY- ] L,EOFADDR- J L,ERRADDR- ] 
NO NO NO 
reLexp 
IGNORE reLexp reLexp 
C,ERROPT= ] L,ISPERR- ] L,LOCK- J 
a NQ NO 


reLexp relexp relexp 
C,NODEV= J. [ NOFIND=}į ` ] L,NOSPACE- J 


Νο NO NO 
reLexp reLexp reLexp 
C,OPENC= ] C,O0PENER= ] L,OPENX- J 
NQ NO 
reLexp reLexp relexp 
C,OPENZ= 1 L,PASSER- 1 €,PGLOCK= 1 
NO NO 
relexp relexp relexp 
[ ,SEQCHK- 1 L,USERERR- J L,WLRERR-7 ] 
Νο NO NO 
relexp This stands for “relative expression"; relexp is normally 


a symbolic address in the AssembLer program. 
CLOSER= An error was encountered while attempting to CLOSE the file 


(for example, when attempting to write Labels). An error 
code detailing the condition is stored in the FCB. 
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COMMON= Control passes to this address if there is no entry for the 
type of error encountered. 


Exceptions: 


ERROPT 
OPENC 
OPENX 
OPENZ 


See Table 5-1, "Use of error exits" at the end of the 
EXLST description. 


DLOCK= This exit applies only to UPAM. 


Control is passed to this exit if another job has set one 
or more Locks necessary to complete the current PAM action 
e macro, and there is danger of a deadLock situation. 


By means of the FCB parameter PAMTOUT, the user can define 
the number of seconds he wishes to wait to obtain a Lock 
before this exit is taken. 


The danger of deadlock exists whenever a user wants to 
obtain further Locks but not all of them are available, 
while he has already set one or more Locks himself. 


If he is given control at this exit, any attempt to obtain 
further Locks before all currently held Locks are released 
wiLL result in abnormal termination of the program. 


Under ISAM, all current Locks must be reLeased before an 
attempt is made to obtain another set of Locks. This means 
that no potential deadlock situation can arise in ISAM. 
Accordingly, control is never passed to this exit during 
execution of an ISAM action macro. 


DUPEKY= If the operand DUPEKY=YES is not specified in the FCB macro 
and duplicate keys occur, control is passed to the 
6 address which has been specified. 


The INSRT macro can be used to insert a record in a file 
when the key of this record already exists (independent of 
DUPEKY=YES). 


EOF ADDR= The end-of-file condition has been encountered with a read 
attempt. 
ERRADDR= A hardware malfunction or an abnormal termination has 


occurred during processing of the file. Status bytes 
consisting of the standard device byte, the Executive flag 
byte and the three sense bytes are stored in the FCB. 
Note: 


SAM read errors use other exits (EOFADDR, ERROPT, USERERR). 
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ERROPT= 


=relexp 


=IGNORE 


=SKIP 


ISPERR= 


LOCK= 


NODEV= 
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This entry applies to SAM input files, and specifies 
functions to be performed in the event of an errored block. 


If a parity error is detected when a block of records is 
read, the bLock is reread a standard number of times before 
it is considered an errored block. After this, the job is 
automatically terminated, unless the ERROPT entry specifies 
a particular reaction in the event of an error. Either 
IGNORE, SKIP or the symbolic name of an error routine can 
be specified. ! 


The functions of these three specifications are: 


The DMS branches to the user routine that performs any 
desired function, i.e. processes the records or takes 

appropriate measures. 

General register O0 contains the address of the errored 
bLock. 


In his error routine, the programmer must not issue any GET 
macros for records in the errored block. In this routine, 
the user can issue Logical macros (GET, PUT) to any file 
other than the file containing the errored records. If the 
program wishes to return to normal processing, the EXRTN 
macro must be issued. If general register 0 contains 
X'00000001', the current block will be skipped and 
processing continues with the next block. Any other code 
indicates that this bLock is to be processed as if no error 
had occurred. 


The error condition is completely ignored, and the records 
are made available to the user for further processing. 


No records in the errored block are made available for 
further processing. 

The next bLock is read and processing continues vith the 
first record of that block. 


This entry does not apply to output files. It applies to 
records with invalid Lengths if the WLRERR name entry is 
not included. 


Not enough space is available to extend the index of an 
ISAM file. With ISAM files, space may be extended either 
for the index or for the data, even though it is the same 
five. 


The condition occurred because the program attempted to 
open a file in a mode other than INPUT and it vas already 
open for another user. Similarly, if the file is currently 
open for another user in a mode other than INPUT and the 
user tries to open the file as INPUT, the same condition 
occurs. This exit should be used only if another section of 
the program can be executed in the event of this condition 
occurring. 


No free device exists upon which the private volume may be 
mounted; or, the private volume is currently being used by 
another user. If the SECURE, HOLD and DROP commands are 
used properly, this condition should not arise. 
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NOFIND- 


NOSPACE- 


OPENC= 


OPENER= 


OPENX= 


OPENZ= 


PASSER= 


PGLOCK= 


EXLST 


A record with the defined key could not be found when the 
GETKY macro was issued, or a record which matched the GETFL 
criteria could not be found within the specified range. 


Insufficient space exists vith which to perform secondary 
allocation or extended output. 


This exit is taken if the file to be opened vas not closed 
during previous processing. Restoration may be attempted 
using the VERIF macro (see section 2.1.7, "Restoration of 
Corrupted Files"). 


If the OPENC operand was explicitly specified in the EXLST 
macro, control is passed to the user at the specified 
address and error code X'ODD1' is issued in field ID1ECD 

of the FCB. 

If the user has not specified the OPENC operand, the system 
continues OPEN processing. 

If an attempt is made during processing to open a file which 
is still open, the user obtains error code X'ODD9' (file 
Locked). If the file is a dummy file and the OPEN mode is 
unequal to OUTPUT/OUTIN, the user receives error code 
X'OSDA'. 


An error vas encountered while opening the file (for 
example, inconsistent FCB, no space allocated for the file). 
An error code detailing the condition is stored in the FCB. 


The FCB has been modified by the information supplied either 
in a FILE command (macro) or via the Catalog. The program 
can now ensure that all parameters are consistent and that 
the OPEN macro can be compLeted vithout errors. If a nev 
file is being created, the FCB is modified by the FILE 
command, although the catalog has not yet been written 

back to the catalog. 

The program cannot be continued until the EXRTN macro 

is specified. 


For a five being opened in either OUTPUT or OUTIN mode, the 
catalog processing has been completed by the time the exit 
is taken; hovever, the remainder of the OPEN processing 
must still be completed. At this stage the program can 
modify the FCB so as to enable further processing. For 
exampLe, the catalog might indicate that the file involved 
is a SAM file, while the user might vant to process it 
using PAM. The program cannot be continued until the EXRTN 
macro is specified. 


An invalid password was specified for a protected file. 


Control is passed to this exit if another job has set one 
or more Locks necessary to complete the current PAM or 
ISAM action macro and there is no danger of a deadlock 
Situation. 


For PAM, the user may use the PAMTOUT operand of the FCB to 
define the number of seconds he wishes to wait in order to 
obtain a Lock before this exit is taken. 


For ISAM, this exit is always taken immediately if the 
Locks requested are not available; i.e the PAMTOUT operand 
is ignored by ISAM. 
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SEQCHK= 


USERERR= 


WLRERR= 
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The following entries apply to ISAM only. 


If this exit is not taken in the case of SHARUPD=YES (i.e. 
if the default value or NO is specified), and the requested 
block is Locked, the user has to wait until he is given 
access to this block. The job is automatically placed in 
the bourse according to its priority. The user is not 
informed of the "busy" status. 


If a file was opened with SHARUPD=YES, the use of all ISAM 
macros may have the effect that control is passed to this 
exit (with the exception of OSTAT). If the PGLOCK exit is 
taken, the “internal pointer" is wrong unless the condition 
is due to a PUTX or ELIM macro (without KEY). 


That is why it is mandatory for this “internal pointer" to 
be repositioned before issuing a macro which assumes it is 
correctLy positioned (e.g. with GET, GETR and GETFL). The 
pointer can be repositioned by using the RETRY macro or any 
of the following ISAM action macros: GETKY, SETL, PUT, 
STORE, INSRT or ELIM (with KEY). If GET, GETR, or GETFL is 
issued before the pointer is repositioned, control is 
passed to the USERERR exit. 


If the condition which caused the PGLOCK exit to be taken 
was due to a PUTX oder ELIM macro (without KEY), the data 
bLock remains Locked and repositioning is not necessary. 


A record to be added to an ISAM file via the PUT macro has 
a key Less than the highest key already present in the ISAM 
five. 


The program has attempted to execute a macro in an illogical 
manner or has called an illegal action, e.g. it has issued 

a WRITE macro to a file opened in INPUT mode, or it 
contains an invalid operand code in PAM. 


The user is given control at this exit if the file is 
opened with SHARUPD=YES and he issues a PUTX or ELIM macro 
(without KEY) without first Locking the data block, or if 
he issues a GET, GETR or GETFL macro after taking the 
PGLOCK exit without subsequently repositioning his file. 


A record with an invalid Length vas read. For fixed-Length 
blocked records, record Length is considered invalid if 
the block Length is not a multiple of the Logical record 
Length (specified in the FCB entry RECSIZE) and Less than 
or equal to the maximum bLock Length (specified in the FCB 
entry BLKSIZE). This permits short blocks of Logical 
records to be read without "invalid record Length" being 
issued. For variabLe-Length records, record Length is 
invalid if the Length of the record is not the same as 

the record Length specified in the block count control 
field. 


U805-J-Z55-5-7600 


Service macros EXLST 


When the program is given control, general register 0Ό 
contains the address of the block containing the error. The 
EXRTN macro must be issued if processing is to continue. If 
register O contains X'00000001', the current block will be 
Skipped and processing continues from the next block. 

Any other code indicates that this block is to be processed 
as if no error had occurred. 


If the WLRERR entry is omitted and the DMS detects an 
invalid record Length, one of the following two conditions 
occurs: | 


1. If the FCB entry ERROPT is specified for the file, the 
record containing the invalid Length is treated as an 
errored bLock and processed according to the user 
program's specifications for an error. 


2e If the FCB entries ERROPT und ERRADDR are not 
specified, the job is terminated. 


The WLRERR entry does not apply to format-U records. 
Records of undefined Length are not checked for invalid 


Length. 


Note: 


Registers 14, 15, O and 1 are DMS parameter registers. Therefore, unless 
explicitly described otherwise, it cannot be assumed that these registers 
have a defined value when the user is given control at the EXLST exit. 


U805-J-255-5-7600 5-17 


EXLST 


Service macros 


The following tables indicate which EXLST exists can be used, and when: 


Error 
exit 


CLOSER 
DLOCK 
DUPEKY 


EOF ADDR 
ERRADDR 


ERROPT 
ISPERR 
LOCK 
NODEV 
NOF IND 
NOSPACE 
OPENC 
OPENER 


OPENX 
OPENZ 


PASSER 
PGLOCK 
SEQCHK 
USERERR 


WLRERR 


STD NSTD BTAM The user can issue 
SAM SAM 
EXRTN 
CLOSE Action macro 


With SAM:N, 
otherwise A 


A (only VERIF 


is practical) 
N 


N 
N 
N 


> 


eh mee * : : Peddie 36 E. 


A 
A 
A 
A 

A A 

A A 

A A 

A A 


Pz 


Table 5-1: Use of error exits (I) 
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See TabLe 5-2 for an expLanation of the abbreviations. 
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Error COMMON FCB key 1) Remarks 
exit exit, if (field Termination 


no exit ID1XITB) 
specified 


CLOSER File is considered closed 


| No further Locks until alt 
existing Locks have been 
reLeased 


DLOCK 


EOFADDR 40 A 

ERRADDR 44 A Error code and/or end byte 
(PAM and BTAM) 

ERROPT 48 A End byte stored in FCB 

ISPERR 50 A 


LOCK 


ΝΟΡΕΥ 14 
NOF IND 58 
NOSPACE 4C 


OPENC 
OPENER 
OPENX 
OPENZ 


Error code stored in FCB 


Δ 15.4 ae: Error code stored in FCB 
Bc MS D UK 


USERERR 


WLRERR Error code stored in FCB 


Table 5-2: Use of error exits for disk files (II) 


Where: 

A = allowed 

Z = applicable 

N = not applicable 


(1) Program terminates if exit was not specified and action was taken 
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EXRTN RETURN FROM ERROR ROUTINES «TYPE R> 


In certain cases, it is necessary to return to the DMS after executing 
certain EXLST exits in order to continue ih ala ta This is effected by 
means of the EXRTN macro. 


This macro is permissible for the following EXLST exits: 


= ERROPT 

-  OPENX 

- OPENZ 

- WLRERR 

Operation Operands 

EXRTN fcbaddr 0 

Ji Δ 

(1) (0) 

fcbaddr This operand specifies the address of the FCB of the file 
whose processing resulted in the error exit (address output 
area). 

(1) Register 1 contains the FCB address. 

0 The current block is to be processed as if no error had 
occurred. 

1 The current block is to be skipped and the next block 
processed. 

(0) Register O contains the value O or 1. 

Note: 


The second operand is significant only in the case of the ERROPT und WLRERR 
exits. 
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FCB CREATE FILE CONTROL BLOCK «TYPE 0» 


The FCB macro reserves space for the File Control Block and, optionally, 
supplies information to it. Additionally, this macro reserves space for the 
Logical routines needed to process the file. 

. The File Control Block is the central source of information for all access 
methods (except EAM). It is always the same size, and always has the same 
field structure. 


- 


Format for disk files 


Operation Operands 
FCB (reLexp) 
LBLKSIZE- ] C,DUPEKY=YES] L,EXIT- 1 
e (STD,absexp) relexp 
ISAM 
L,FCBTYPE-1SAM [IJ C,FILE=filename] L,FORMZSHORTl 
PAM 
NO NO 
L,IOAREA1- J L,IOAREA2-7 1 L,IOREG-regnol 
relexp relexp 


C ,KEYARG=relexp L,KEYLEN-absexpl [,KEYPOS=absexp]] 


INPUT 
OUTPUT 
| EXTEND 
C,LINK=Linkname] L,LOGLEN-absexpl [L,OPEN- ] 
UPDATE 
INOUT 
OUTIN 


C,OVERLAP=YES] [,PAD=absexp] [,PAMREQS=absexp] 


C,PAMTOUT=absexp] [,PASS=password] L,RECFORM- 1 


YES 
C,RECSIZE=absexp] [,RETPD=days] c/SHARUPO=| NO h 
WEAK 
MAX 
ha C,VARBLD=regno] 


C,VALLEN=absexp] C -VALPROP=| 
MIN 


YES YES 
Γ,νπουτ- 1 C,WRCHK= 
NO Νο 


code 
C,OPTION= ] 
(code,code) 
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BLKSIZE= 
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=(STD, 
absexp) 


Service macros 


This operand specifies the size of the file's buffer. 
{Form 1): 


This operand specifies that the buffer is one PAM block 
(2048 bytes) in Length. 


(Form 2): 


This entry specifies that a buffer is the number of PAM 
blocks specified in "absexp" (absolute expression, which 
may be any value from 1 to 16). The maximum value of 
"absexp" is 16, which allows a buffer Length of 32768 bytes. 


Programming notes: 


- If this operand is used at OPEN time (for example, to 
allocate buffers), BLKSIZE=STD (form 1) is always 
assumed by the PAM action macros. 


- No Logical record can exceed BLKSIZE. No ISAM variabLe- 
Length or fixed-Length Logical record and no SAM 
variabLe-Length Logical record can exceed BLKSIZE-4. 


- Strictly speaking, this operand defines the buffer size 
(i.e. the volume of data transferred to or from an I/O 
device). 


ExampLe: 
BLKSIZE=(STD,3) 


The buffer is 2048 x 3 = 6144 bytes Long; the physical 
block size is 2048 bytes. It should be noted that a Logical 
record can be up to 6144 bytes Long (which impLies that 
Logical records can cross physical block boundaries). 


There are two principal reasons why the user might specify 
(STD,absexp) instead of STD. 


1. The Logical record exceeds 2048 bytes. 


2. The Logical record is uneconomical for a block size of 
2048 bytes. If the user has fixed-Length (format-F) 
records of 1500 bytes and if BLKSIZE-STD is specified, 
then 548 bytes of each bLock are vasted. 


Hovever, if the user specifies BLKSIZE-(STD,3) then 
6000 of the 6144 bytes (i.e. 2048 x 3) are used, 
which wastes only 144 bytes per three blocks. The use 
of very Large bLock sizes, however, increases paging 
activity. 


When specifying forms 1 or 2 for BLKSIZE, the user 
does not have to be concerned about the key. The key 
is always read from or written into the FCB. 


DefauLt value: STD (form 1) 
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DUPEKY= This operand specifies that duplicate keys are permissible. 


If this operand is omitted and duplicate keys are 
encountered, control is passed to the address supplied in 
the user's EXLST macro (default value). 


EXIT= This operand specifies the address of an exit routine. If 
the value of this operand is enclosed in parentheses, the 
address is actually the address of the user program's exit 
routine. If the value of this operand is not enclosed in 
parentheses, the address is assumed to be the address of 
the EXLST macro. 


It should be noted here that if the exit is taken, 9 
regardless of its type, an indicator is set in a byte in 

the FCB so that the user routine can identify the specific 

exit condition. 


e Moreover, if the exit is taken because of a hardware error 
during I/0, a 5-byte area in the FCB is also set to contain 
the following bytes from the CCB: 


- standard device byte 
- Sense bytes 1, 2, 3 
- Executive flag byte. 
See Appendix Α. 5 (Table A. 3-1) for details of the sense 
bytes. The Executive flag byte and standard device byte are 
defined in the CCB DSECT (IDCCB). 
Warning: 
In the event of a non-specified condition, a branch is made 
to the Location defined by the COMMON operand in the EXLST 
macro. 
If any other conditions are specified by means of 
appropriate operands, a branch is made to the relevant 

© exit. The COMMON operand saves the programmer the effort of 
writing a Lengthy EXLST macro and thereby generating a 
Large table of error exits. 
Example: 
EXLST OPENX-LOC1,COMMON-LOC 
The OPENX condition causes control to be passed to LOC1. 
ALL other conditions (for example, EOFADDR, DUPEKY) cause 
control to be passed to LOC. 


Default value: 


No exit address is created; consequently, any undefined 
conditions will cause abnormal program termination. 
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FCBTYPE= 


FILE= 


FORM=SHORT 


LOAREAT-NO 


-reLexp 


IOAREA2-NO 
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This operand specifies the access method to be used to 
process the file: 


ISAM 


PAM 


This operand specifies the fully qualified file name of a 
file, a generation (with absolute or relative generation 
number), or the name of a temporary file. 


The name of a file generation group is not permitted. 


Default value: FCB name (i.e. symbol in the name field). 


This operand specifies that space is not to be reserved for 
the corresponding Logical routines. Such routines are 
required by SAM and ISAM for blocking and debLocking 
records in the I/O buffer. 


Default value: 


Space is reserved where necessary. It should be noted that 
PAM never requires the Logical routines in the user 
programs accordingly, this operand is ignored for this 
access method. 


Note: 


The SHORT operand is intended for certain applications 
only. If it was specified for normal ISAM or SAM 
processing, the FCB cannot be opened. 


This operand specifies that no buffer (area) is to be 
assigned at OPEN time. This value cannot be specified for 
SAM and ISAM. 


This operand specifies the address of the buffer in order 
to enable the file to be processed. If this area is Less 

than or equal to 4096 bytes (one page), it must be fully 

contained on one page and be aligned on a word boundary. 

If this area is Longer than one page, it must: 


1. begin on a page boundary 
2. be virtually contiguous 
3. not cross a segment boundary 


DefauLt vaLue: 


The DMS dynamically requests buffer space (class 5 memory) 
at OPEN time. 


This operand specifies that no second buffer is to be 
allocated at OPEN time. The user is cautioned that if this 
value is specified for SAM, the system cannot perform any 
overLapping I/O operations. The value cannot be specified 
for ISAM. 
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IOREG- 


KEYARG= 


macros 


=relexp 


FCB 


This operand specifies the address of the buffer, in order 
to enable the file to be processed. If this area is Less 
than or equal to 4096 bytes (one page), it must be fully 
contained on one page and be aligned on a word boundary. 
If this area is Larger than one page, it must: 


1. begin on a page boundary 
2. be virtually contiguous 
Jj. not cross a segment boundary 


Default value: 


The DMS dynamically requests buffer space (cLass-5 memory) 
at OPEN time. 


Programming notes for IOAREA: 


When a file is opened, the IOAREA addresses are created 
(if necessary) and verified. They are then moved to system 
memory. Consequently, any changes concerning the addresses 
are compLeteLy ignored in the FCB. 

For neu addresses to become effective, it is necessary to 
cLose the FCB and to issue another OPEN macro. 


This method of processing minimizes internal system 
processing time (overhead), as the system need not check 
IOAREA addresses prior to each action macro to ascertain 
whether they have been modified. PAM und BTAM (see the "DMS 
Tape Processing" manual) also allow the user to specify 
buffer areas in their action macros. These buffer addresses 
are, of course, validated every time the action macros are 
issued. Additionally, PAM and BTAM allow the user to select 
IOAREA1 and/or IOAREA2 in their action macros. 


During the period when a file is open, the user must not 
modify the IOAREA except in connection vith an action 
macro. If a file is opened in a class 1 program, IOAREA1 
and IOAREA2 must be specified as "reLexp" or NO. 


If a SAM file is opened in UPDATE mode, the IOAREA2 buffer 
is not used. 


If NO is specified for IOAREA1, the value for IOAREA2 must 
also be ΝΟ. If IOAREA1 is specified as "revexp", the value 
specified for IOAREA2 must be NO or "reLexp". If no value 

is specified for IOAREA1, the same must apply to IOAREA2, 

or NO must be specified. 


Alignment of the buffer is only necessary if its address is 
greater than X'800', l 


This operand specifies the general register (2 through 12). 
which contains the address of the current record (absexp). 
This implies that records are to be processed in Locate mode 
(applies to SAM and ISAM only). 

DefauLt vaLue: 

Move mode is assumed. 


This operand specifies the address of the key. This applies 
to certain ISAM action macros (GETKY, ELIM, GETFL, SETL). 
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KEYLEN= 


ΚΕΥΡΟΣΞ 


LINK= 


LOGLEN= 


OPEN= 
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This operand specifies the number of bytes in the record 
key. The key must be of the same Length in every record 
(1 - 255 bytes) 


Default vaLue: 8 bytes 


This operand specifies the position of the first character 
of the record key vithin the record. The key must be 
Located in the same position of every record. The first 
byte in the record must be 1. If format-V records are 
specified, the 4-byte control prefix is considered to be 
part of the record. 


Default values: 
1 for format-F records; 
5 for format-V records. 


This operand specifies the file Link name (up to eight 
characters). It provides the Link between the FCB and the 
TFT if data from a FILE command/macro is to be used to 
modify the FCB. Thus, unique file Link names must be 
provided for the FCBs of a program if modification of these 
FCBs is planned. 


If the file Link name for an FCB is omitted, a Link name 
consisting of blanks (X'40') is generated. Specifying 
"LINKz2,..." (null operand) causes the generation of a Link 
name consisting of binary zeros. This prevents the FCB 
being modified by a FILE command/macro. In this case the 
OPEN macro creates a TFT entry containing blanks or binary 


zeroes as the Link name. 


It is therefore not advisable for the user to omit the Link 
name or to specify the null operand. 


This operand specifies the Length of the Logical flag for a 
flagged ISAM file. 

Default value: O0 

This operand specifies in which mode the FCB is to be 
opened. It should be noted that the OPEN macro can override 


this specification. 


Valid OPEN processing options for the various access 
methods are shown in the table below (disk files only): 
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OVERLAP= This operand specifies that buffered or overlapped read 
operations are desired when more than one data buffer 
exists. 


This applies to the ISAM macros GET und GETR. 
Default value: 


No I/0 operations are performed in advance, so as to bring 
about overlapping. If this operand is not specified, ISAM 
uses IOAREA2, not for anticipatory I/O but as a work area. 


PAD= This operand specifies the percentage of buffer Length to 
be reserved during creation of an ISAM file for Later 
insertion or expansion of records in the data blocks. 


Default value: 
e Fifteen percent of the data space is reserved. 


PAMREQS= This operand specifies the maximum number of asynchronous 
I/O requests that the user can issue for this PAM file at 
any given time. This maximum can be any value from 1 to 
100. 


Default value: PAMREQS=1 


PAMTOUT= This operand specifies how many seconds a job is to wait 
for one or more PAM Locks. Should the requested Locks’ fail 
to become available after that period, a branch is made to 
the EXLST exit DLOCK or PGLOCK. The minimum value of 
this operand is 0; in this case, control is returned 
immediately, regardless of whether or not the requested 
Locks are availabLe. 


The maximum value is 43200 (seconds). 


Default value: PAMTOUT=0 


PASS= This operand specifies the password needed to access the 
ς file (absexp). The password can be up to 4 characters Long. 
This field is filled with zeros to the Left or, if it is 
Longer than 4 characters, it is truncated on the Left. The 
method is the same as the one utilized for address constant 
processing by the AssembLer; 
e.g. the expansion is DC AL4 (password). 


ExampLes: 

PASS=C*ABC* gives (00C1C2C3) in the FCB 
PASSzX'0102' gives wanda: in the FCB 
PASS=C* ABBCDEF * gives (cscdbebwL - in the FCB 
Default value: (00000000) ° 
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RECFORM= 


RECSIZE= 


RETPD= 


SHARUPD= 


=YES 
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This operand specifies the record Length type. 
Fixed-Length records. 
VariabLe-Length records. 


Records of undefined Length. This value is not permissible 
for ISAM. The combinations (U,A) und (U,M) have no effect. 


"AT specifies that the first data byte is an ASA control 
character; 


"n" specifies that the first data byte is interpreted as 
a control character for EBCDI code. 


"a specifies that no print control character is present. 


Although the PAM File Control Block accepts this operand, 
it is ignored by the action macros. 


This operand specifies the Length in bytes of a Logical 
record for format-F records. If RECFORM=V is specified, the 
RECSIZE entry is not verified; the maximum record Length is 
here always equal to the buffer size. 


For format-U records, this operand specifies the generat 
register (2 through 12) which is to contain the Length of 
each record. Whenever a format-U record is read, the DMS 
supplies its Length in this register. If a record of 
undefined Length is to be written, the user must place the 
Length of the record in this register. 


Although the PAM File Control Block accepts this operand, 
it is ignored by the PAM action macro. Nevertheless, it can 
Still be specified, as a file created vas PAM can be pro- 
cessed by SAM. 


This operand specifies the period (in days) during which a 
file is to be retained, and stipulates when overwriting, 
updating or erasing of the file is permitted. However, it 
cannot be used automatically to erase a file from the 
system (absexp) once the retention period has expired. 


"days" must be a decimal integer, the maximum value of 
which is calculated from the difference in days between 
the end of the century (31.12.99) and the current date. 


Default value: O days (i.e. the file can be overwritten 
or erased immediately). 


This operand specifies whether a UPAM or an ISAM file can 
be shared by more than one job for the purpose of 
Simultaneous updating. 

Shared updating is possible. 


Shared updating is not possible. 
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=WEAK 


VALLEN= 


VALPROP= 


=MAX 


=MIN 


FCB 


This entry is permitted for UPAM files only. 

WEAK ensures write protection. Only one user at a time can 
write to the file. 

Read protection remains the responsibility of the user, who 
has the following options: 


* he can implement read protection by means of his own 
programming measures. 


* he can assume that a record read for the second time 
will have been modified in the meantime. 


The following table illustrates the various competing 


Levels, together with the types of protection offered in 
each case: 


Number of users who can Protection type 
[reos [enavor [write | σα 


and M 


SHARUPD 
options 


YES 


Notes: 


- The operand WEAK is supported for PAM files only. 

- With SHARUPD=WEAK, a user job can run either on one 
processor, or on tuo different processors that are 
Linked via shareable private disks (SPD). 


- The SHARUPD combinations permitted in the case of one or 
more processors are specified in section 6.2.1. 


- If FCBTYPE * PAM, the WEAK operand is processed as NO 
(i.e. SHARUPD=NO). 


This operand specifies the Length of the value flag that can 
be specified for ISAM files in addition to the ISAM key. 


If LOGLEN or VALLEN is specified, 
KEYLEN + LOGLEN + VALLEN must be Less than or equal to 255. 
Default value: O0 


This operand specifies how the value flags in ISAM files 
are to be entered in the index blocks: 


The highest value flag from all the records in the data 
block is entered in the index entry. 


The Lowest value flag from all the records in the data 
block is entered in the index entry. 
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VARBLD= 


WROUT=YES 


-NO 


WRCHK=YES 


WRCHK=NO 
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This operand specifies the general register (2 through 12) 
in which the DMS stores the amount of free space in the 
block to be written (absexp). This specification is 
necessary for SAM files when format-V records are to be 
created in Locate mode. 


The contents of ISAM buffers (data and index bLocks) are to 
be written back immediately after they have been modified. 


Writing back is not performed automatically after each 
modification. 


Notes: 


- The WROUT function enhances security when processing 
ISAM files. In the event of a system crash only the 
records processed by the Last macro can be corrupted or 
Lost. (Exception: After a PUT macro, a buffer is written 
back only when completely filled). 


- The increased number of I/O operations reduces 
throughput. 


- The WROUT function takes effect after the ISAM action 
macros STORE, ELIM, INSRT, PUTX and PUT (after PUT, only 
when the buffer is completely filled). 


- ISAM SHARED UPDATE includes the WROUT function, so in 
this case the operand is irrelevant. 


- A value other than YES or NO will always result in an 
error message. 


- The value in the FILE command or the FILE macro has 
priority over the value in the FCB macro. 


- The operand value specified in the FCB macro appLies 
only if no operand, or a null operand (i.e. WROUTz,...), 
is entered in the FILE command or the FILE macro. 


A read-after-vrite check is performed for all data. This 
means that written records are checked only for their 
readability and not for their contents. 

As a result, write errors on the disk are recognized in 
good time and can be recovered by taking the appropriate 
measures. If the error cannot be eliminated, a branch is 
made to the ERRADDR routine (via EXLST). 


Notes: 

- The read-after-write check requires an additional 
turning of the disk, which adversely affects 
system performance. 

- This specification is not contained in the catalog 
entry of the file, i.e. it must be entered explicitly 
each time a file is to be processed and be available 
when the file is opened. 


No read-after-write check is performed. 
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OPTION=code This operand can be used to specify a List of options. 
The following can be specified for "code": 


GLODEF If the file name is specified without an explicit 
user ID and the file cannot be found under the 
user ID of the person making the call, a second 
read attempt is performed under the ID which was 
defined in the class 2 option DEFLUID (see the 
"System Generation” manual). 

Cf. the sections on "Retrieving Files” and 
"Opening Fives". 


WARN In FCB field ID1WCB, return codes are stored as 
warnings, without execution being interrupted 
(exit routine). 
This means, for example, that screen masks are no 
Longer destroyed and unassignabLle messages are no 
Longer encountered when procedures are executing. 


e The user himself decides when and if to evaluate 
the corresponding field in the FCB and how to 
respond. | 


The following warning codes are stored at the 
present time: 


O44F PubLic space Limit exceeded, when 
enforcement is permitted. 
0440 Public space saturation Level 3 exceeded. 


The default value specifies that no codes are 
stored. 
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Return information 
Return code OD33 stored in FCB field ID1ECB by the OPEN command has the 


following meanings, depending on what specifications the user has made in 
the file name and in the OPTION operand. 


File name OPTION Meaning of 0D33 


:C: SUSER. FILE any The file does not exist under the ID S$SUSER 
specification on PVS :C: 


SUSER. FILE any The file does not exist under the ID SUSER 
specification on the default PVS of SUSER. 


SFILE any The file does not exist under the ID 
specification generated for DEFLUID on the PVC specified 
therein. 


ID nor under the ID generated for DEFLUID 
on PVS :C: 


:C: SFILE any The file does not exist under the ID 
specification generated for DEFLUID on the PVS :C: 

FILE not The file does not exist under the caller's 
GLODEF ID on the default PVS. 

FILE GLODEF The file exists neither under the caller's 
ID on the default PVS nor under the ID 
generated for DEFLUID on the PVS specified 
therein. 

: C: FILE not The file does not exist under the caller's 

GLODEF ID on PVS :C: 
:C:FILE GLODEF The file exists neither under the caller's 


If the user is given control in an OPEN exit (OPENX, OPENZ, OPENC), the 
compLete file name (with CATID and USERID) is in field IDAIFILE of the P1FCB 
at this time. This is also the case following successful completion of 

OPEN. Following an OPEN error or following a CLOSE on the FCB, field ID1IFILE 
is again given the file name specified by the user. 


Any modification of the file name in the IDIFILE field within an OPEN exit 
routine is ignored. 


This behavior may be modified for users whose programs expect the file name 
in the FCB to be unchanged. 
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Programming notes: 


When an FCB (file) is opened, most of the processing operands are moved into 
system memory (P2FCB) after creation and verification. Any change in these 
operands is therefore ignored. New values become effective only by closing 
the FCB and reissuing the OPEN macro. Changes to the FCB of an opened file 
may cause abnormal program termination or unpredictable file processing. 


Null operands such as "FCBTYPEz,..." do not initiate the default function. 
In this case, the Assembler Listing indicates that an operand vas not 
fully defined at assembly time and must be specified at execution time. 


Operands which may η 
be supplied via the 
catalog 


FCB Operands valid 
operands | operand in the FILE 
command 


e DUPEKY 
EXIT 


IOAREA1 
IOAREA2 
IOREG 


X X X X X x x >< 


XHXHHH X X HK x x HH 


OVERLAP 
PAD 
PAMREQS 
PAMTOUT 
PASS 
RECF ORM 
RECSIZE 
RETPD 

e SHARUPD 
VALLEN 
VALPROP 
VARBLD 
WROUT 
WRCHK 
OPTION 


X X X X HH 


HH X X HH xo ox HH 


κκ — X X X XXX 


X X 2X X XX 0X 0X XX OK 0X OX OH b 0X X X OX 0X OK OX 0X OX XO OK OK OK «OK XX 


κ X X X X x X x 


Table 5-3: Summary of FCB macro operands valid for each access method 
(for disk files only) 


Where: 


I 
X 


operand accepted but ignored by action macros 
operand may be specified 
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Note: 


If an operand is omitted, the appropriate default value is assumed. If a 
null operand is specified (i.e. the operand value assigned is the blank 
character string, e.g. in the form FCBTYPE=,) it is assumed that the 
operand value will be supplied via a FILE command/macro, or from a file 
catalog entry. 


Exception: 
Operand LINK= 


FCBAD CREATE FCB ADDRESSES «TYPE 0; 


For all DMS macros following each other statically in a program the code is 
generated in such a vay that the File Control BLocks may be symbolically 
addressed outside the base register. The FCB addresses are here stored in 
the Literal pool. This macro thus facilitates program conversion from BS1000 
to BS2000. 


Operation Operands 


FCBAD 
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OPEN OPEN FILE «TYPE R> 


A file must be opened by means of the OPEN macro before it can be processed. 


Operation Operands 
OPEN fcbaddr mode 
E ] 
(1) (0) 
fcbaddr This operand specifies the address of the File Control 
bLock. 
(1) The address of the FCB is in register 1 (addexp). 
- mode This operand specifies the OPEN processing mode. 
(0) The mode is in coded form in the Least significant byte of 


register O. 


(not specified) 


INPUT X'O1" 
REVERSE Xx'02"' 
OUTPUT X' 0^4" 
EXTEND X*08" 
UPDATE X'10' 
e INOUT Χ'21" 


OUTIN 


Default value: 


The OPEN mode is specified in the FCB or in the TFT; 
otherwise INPUT is assumed. 


Note: 


The characteristics of the various OPEN modes are described under the 
appropriate access method. 
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6 ACCESS HETHODS 


6.1 GENERAL 


6.1.1 Overview of the Purpose and Functions of Access Methods 


Hhat purpose do access methods serve? 


The DMS access methods transfer data between a file and the address space of 
© a job when requested by the job to do so and when the file concerned is open. 


Technically speaking, this signifies the transfer of data between the 
peripheral storage facilities and the main memory of the CPU, with the DMS 
assuming responsibility for the complicated handling of devices and offering 
the user interfaces for accessing: 


e Logical records: 
These are the elements of the Logical structure known as a file; 


e buffer contents: 
From the program's point of view, these are the units of data transfer and 
storage (see also sections 6.1.2, "Relationships between Access Methods" 
and 6.1.4, "Relationship between Logical Record, Buffer and PAM Block"). 


How do access methods function in principLe? 


When a user program accesses the contents of a file, the following 
processes can be distinguished: 


9 The DMS transfers data blocks between peripheral storage and main memory. 
© This operation is essential for all access methods. 


€ That part of main memory which accepts one or more data blocks or from 
which data blocks are transferred to peripheral storage is called a 
buffer. The buffer belongs to the address space of the job which 
initiated the I/O operation. 
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Job’s address 
space 


«ο means: Initiate an I/O operation 


r means: Transfer data blocks 


Fig. 6-1: Transferring data blocks 


e The following procedure depends on whether access is block-oriented or 
record-oriented: 


In the case of block-oriented access, the user program and the DMS need 
only know which is the current buffer if alternate buffer operation vas 
specified when the file was opened. (Alternate buffer operation serves 
to accelerate processing; the program processes the contents of one 
buffer while the DMS makes available or writes out another buffer). 
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In the case of record-oriented access, the following facilities are 
provided: 


- Move mode 
The DMS moves a Logical record between the buffer and a work area 


belonging to the program. The program can freely select this work area 
whenever it accesses a Logical record. 


Job’s 
storage space 


Work area 


4——_ means: Read/write call for a logical record 


e means: Transfer a logical record 


Fig. 5-2: Move mode for record-oriented access methods 
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Locate mode 


The DMS transfers to the program an address which points to a position 
in the buffer, either from which the program can read a record it has 

Located, or to vhich it can write a record. A register for transferring 
the address must be specified when the file is opened (see the operand 


IOREG=regno in the FCB macro). 


Note: 


Access to a Logical record requires a buffer transfer only if the 
current buffer does not contain the record required or if, when a 


file is created sequentially, the buffer is full. 


Job’s 
address space 


E 


Access : 
SAM pid ISAM for trans- 
an ferring the 


address 


4—— means: Read/write call for a logical record 


=p means: Transfer an address 


ood) means: Pointer to current logical record (= address of record in the buffer) 


6-3: Locate mode for record-oriented access methods 
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Selecting an access method 


The selection of an access method depends on the particular requirements of 
the problem to be solved. 


The DMS offers the user the following access methods: 


BLock-oriented Record-oriented 
UPAM ISAM 
EAM SAM 


The following table is intended as an orientation aid in selecting an access 


method. 


Access 


methods Access Record type 


Fig. 6-4: Suitable access methods for specific requirements 
*) Suitable for work files only (see section 6.5, "EAM"). 
L how t t : 
Το find a BS2000 access method which satisfies the following requirements: 
- Disk file processing | 
= Record-oriented access 


= Record type = variable Length 


The Line followed by "xx" satisfies these requirements; i.e. ISAM. 
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6.1.2 Relationships between Access Methods 


The central DMS access method is privileged PAM (Privileged Primary Access 
Method = PPAM). 


Privileged PAM operates with a buffer Length of 2048 bytes or an integral 
multiple of 2048 (maximum Length = 16 x 2048). It can process only those 
disks that are preformatted into blocks of 2048 bytes in Length (see also 
the "System Controller's Guide" and "System Generation" manuals). These 
bLocks are also called PAM blocks. 


Privileged PAM operates in association with the following access methods: 


- UPAM 
- EAn 
- ISAM 


- SAM (when accessing disk files and tape files with standard blocks) 


Access method BTAM, on the other hand, operates independently of privileged 
PAM; this also applies to the access method SAM when accessing tape files 
whose block Lengths are incompatible with the block Length of privileged 
PAM. This relationship is shown in the following diagram. 


Privileged PAM 


Standard block size (PPAM) | EXCP 
B. οι 
Non-standard 
block size | 
| GRE 
Privileged 
oo pit users | 
Lou e a scd 


Fig. 6-5: Relationships of access methods to privileged PAM (PPAM) 
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6.1.3 Logical Record Formats 
Three types of Logical record format may be distinguished: 


Format F (fixed-Length records) 


Records having this format appear as follows: 


User data 


Byte Ό Last byte 


A file is designated as having "fixed-Length records" if it vas set up with 
the specification RECFORM=F. The record Length should be defined with the 
operand RECSIZE-Length (see the FILE command and FCB macro). 


Format V CvariabLe-Length records) 


Records having this format appear as follows: 


RL Reserved ——À User data 


Byte O Byte 2 Byte 4 Last byte 


RL: Record Length - Length of user data * 4 


A file is designated as having "variabLe-Length records" if it was set up 
with the specification RECFORM=V (see the FILE command and FCB macro). 
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Format U (records of undefined Length) 


Records having this format appear as follows: 


Buffer 


User data Undefined 


Byte O of buffer Last byte 
= | (soe text) 
Byte 0 of record 


To process records of undefined Length, the user must specify a register 
when the file is opened which will contain the currently applicable Length 
at any particular time (see the operand RECSIZE=regno in the FCB macro). 

A file is designated as having records of undefined Length if it was set up 
with the specification RECFORM=U (see the FILE command and FCB macro). 


6.1.4 Relationship between Logical Record, Buffer and PAM Block 


As far as the DMS is concerned, a Logical record is a data element that 
cannot be further subdivided. This applies both to searching in a file -- in 
the case of record-oriented access -- and to transferring data to and from 
the calling program. This means that a buffer must be at Least as Long as 
the Longest record in a file, a point that should be observed when selecting 
the buffer Length. 


The buffer Length must always be compatible with the block format of 
privileged PAM. 


Therefore only the following values are permissible buffer Lengths: 
n*2048 bytes (where n is an integer in the range from 1 < n < 16). 


The buffer Length can be defined for each file with the operand 
BLKSIZE-(STD,n); see the FILE command and FCB macro. 
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Examples of record/buffer/bLock relationships in SAM and ISAM: 
1. Given: | 


Format-F records of 100 bytes 
BLKSIZE-(STD,2) 
Buffer size = 2 blocks (4096 bytes) 


The buffer consists of 40 Logical records; the rightmost 96 bytes of the 
buffer are unused. Nevertheless, two 2068-byte blocks are written. It 
should be noted that record 21 of the buffer is spread over two blocks; 
the first 48 bytes are in block 1, the Last 52 bytes are in block 2. 


2. Given: 
Format-F records of 1500 bytes 


Standard bLocks 
Buffer size = 1 block (2048 bytes) 


© This is a bad choice since 548 bytes are wasted. A desirable buffer size 
would be three blocks (6144 bytes). The buffer could then contain four 
records, and 6000 out of 6144 bytes could be used. Three blocks, each of 
2048 bytes, are written. | 


3. Given: 
Format-F records of 8192 bytes 
BLKSIZE=(STD,8) 
Buffer size = 8 blocks (16384 bytes) 
Each buffer contains two Logical records; each Logical record comprises 
four bLocks. 


Buffer 16384 


Logical records Record 1 
stocks eer Tere l 
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6.2 UPAH «USER PRIMARY ACCESS METHOD» 


UPAM ist the primary, block-oriented access method in BS2000 for random 
(direct) access. 

It provides for read or write access (including deletion) to any block in 
the file at any time. 

The block Length is 2048 bytes. Record structures within the blocks remain 
unknown to UPAM. 


BS2000 disk file User program 


Block number 


OPEN file (OPEN macro) 


READ or WRITE 
block πο. k (PAM macro) 


Access to 
blocks 


CLOSE file (CLOSE macro) 


File Control Block (FCB macro) 


ΙΟ areas 


(IOAREA 1/2) 


Dou pe 
DEB 


Data transfer 


€«— initiate UPAM Ι/Ο operation 
E ME A second I/O area may be used if desired 


ανασα asilo dita 


Fig. 6-6: Basic mode of operation of UPAM 
UPAM offers the following processing facilities: 


e Generation of disk files, not extending over more than one disk. The user 
himself must program access to Logical records in these files (e.g. 
sequential access or associative access by means of the hash method). 


e Reading of SAM and ISAM files (OPEN-INPUT) and their transfer to other 
voLumes (e.g. from disk to tape). 
The file attributes are always stored in the FCB, e.g. BLKSIZE, RECSIZE, 
RECFORM. 
This enabLes the user to program access to Logical records. 
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Exception: 


A file generated by SAM or ISAM cannot be opened in UPDATE mode for 
UPAM. 

In addition, an ISAM file opened for ISAM in SHARED UPDATE mode cannot 
be opened for UPAM. 


Note: 


With ISAM files, the relationships between the indices and the Logical 
records are very complex; accessing Logical records requires a 
correspondingly high degree of programming outlay. As a result, it is 
impractical to process ISAM files with UPAM. 

However, UPAM can be used to transfer an ISAM file, block by block, to 
tape. 


e Shared (file) update b 


- Multiple parallel jobs can process a UPAM file simultaneously (the file 
must not have been generated by SAM or ISAM). 


e Chained I/O 


A single PAM macro can be used to input/output up to 16 consecutive PAM 
bLocks of a five. 


e Chaining of PAM macros in List form 


Up to 255 PAM macros in List form (these need not necessarily all refer 
to the same file) can be handled by a single UPAM I/O request, i.e. only 
one SVC is required. 

The chaining of PAM macros serves to optimize the runtime behavior of 
user programs (as does chained I/O). 


e Informing the user job upon termination of a UPAM I/O operation and 
starting a contingency task (eventing mechanism). 


- 6.2.1 Opening a UPAM FiLe 


The file can be opened in the following modes: 

1. INPUT: Retrieve blocks from an existing file. 

2. OUTIN: Create a new file and, if required, retrieve blocks from this 
EU Ms Asi is being created, Labels are generated. 

5.  INOUT: Retrieve blocks from an existing file and, if necessary, insert 


and/or replace records. No Labels are generated since the file 
is assumed to exist already. 
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OPEN-mode| INPUT OUTIN INOUT 
UPAM 
macro functions 


RD, RDWT, LRD, LRDWT X X X 
WRT, WRTWT, WRTWU v X x 
WT, CHK X X X 
LOCK, UNLOCK, SETL ! X X X 


Table 6-1: UPAM macro options and permissible OPEN modes 

The first user can select any combination of values for OPEN and SHARUPD 
when opening his UPAM file. Table 6-2a below defines the combinations of 
OPEN and SHARUPD which another user can use to open a file that has already 
been opened. If the file vas opened by more than one user, then the OPEN/ 
SHARUPD combination of another user is compared with each of the previous 


ones. For the file to be opened again, each of these comparisons must be 
successful. 


Mono- 
processor USER B 


SHARUPD=YES SHARUPD=NO SHARUPD=WEAK 
OPEN mode INPUT} INOUT| OUTIN| INPUT] INOUT| OUTIN| INPUT] INOUT| OUTIN 
WEBER CA MA 
CODE 
Eo aA 


> οπως 


ων... ως 


Table 6-28: Permissible SHARUPD/OPEN combinations 


Illegal combinations result in an OPEN error. 
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Multi- 
processor USER B/SYSTEM 2 


SHARUPD=NO SHARUPD=WEAK 


INOUT| OUTIN 


o 
"U 
m 
ra 
3 
ο 
a. 
© 
54 
- 
"U 
c 
her 
H 
z 
eo 
c 
«ἡ 
o 
c 
mr 
Hi 
z 
H 
Ζ 
"U 
c 
«d 
þei 
A 
O 
e 
har 
eo 
c 
ur 
H 
a 
= 
zZ 
"U 
c 
= 


> ὍΠΩΣ 


e ZMAN 
Ln. 
z 
Ὅ 
ς 
- 


Table 6-20: Permissible SHARUPD/OPEN combinations 


The term "multiprocessor environment" refers to a network comprising several 
systems interlinked by means of shareable private disks. 
The combinations for accessing from 2 systems are illustrated in the table. 


C ILLegal combinations result in an OPEN error. 
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6.2.2 Shared FiLe Update 


If a UPAM file is to be processed by multiple parallel jobs, the operand 
SHARUPD=YES must be specified in the FCB in each case (see also section 
6.2.1, "Opening a UPAM File"). 


The following points should be noted with regard to shared update of UPAM 
files: 


e In UPAM, there is no implicit Locking/unLocking of PAM blocks. 
The user must explicitly request or release every Lock himself. 
CLOSE is the only exception: before the file is closed, any PAM blocks 
Still Locked for this job in the file are unlocked. 


e Locking a PAM block by no means prevents other jobs from reading it or 
writing to it. What it does prevent is Locking of this PAM block by 
another job. Therefore, when updating the same UPAM file, all jobs 
should proceed in the following sequence: 


LOCK --» READ --» WRITE --» UNLOCK 
In this way, the integrity of the file is ensured. 


The user should not attempt to request other resources for exclusive use 
while he has PAM blocks Locked. This could Lead to a deadlock situation 
(EXLST output DLOCK). | 


€ No more than 255 PAM bLocks can be Locked in any single job. 


e Within a given job, the same PAM block must not be Locked more than 
once. 


UPAM examines the FCB field 101τουτ (value of the PAMTOUT operand) 
vhenever one or more Locks are requested. 


The Length of this interval can therefore be modified dynamically by the 
user program as Long as the file is open. When UPAM receives two or more 
requests for a Lock within an operand List chain (operand CHAIN- in the 
PAM macro), the PAMTOUT vaLue of the FCB indicated by the first request 
for a Lock in that chain is applicable to this chain of requests. 

Should no Locks be available immediately, the job is queued for the 
number of seconds specified in the ID1TOUT field. If the Locks requested 
are still not available, either the DLOCK or the PGLOCK exit is taken, 
depending on vhether or not the job has PAM bLocks Locked at that time. 


Φ Any LOCK or UNLOCK operation applied to a file previously opened with 
SHARUPD=NO is treated as a NOP. 


Exception: 
File pointer updating. 


e If PGLOCK occurs, the program can continue normally, e.g. make a new 
attempt to Lock the block after a waiting time. If DLOCK occurs, a 
muLtipLe Lock has been attempted, if not implemented, and the program 
becomes unstable. As Long as it is in this unstable state, any attempt to 
Lock a PAM block before all current Locks are unlocked will cause the 
program to abort. Only when all current Locks have been unlocked, either 
during the routine for DLOCK or thereafter, will the program become stable 
again and be able to request Locks as usual. 
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6.2.3 Chained I/O 


Chained I/0 permits the transfer of up to 16 Logically consecutive PAM 
bLocks with a single PAM macro (not to be confused with the chaining of PAM 
macros in List form with the operand CHAIN=). 

Chained I/O reduces the number of 1/0 operations (and interrupts) and thus 
saves processing time. However, it does somewhat increase main memory 
requirements and thus also the amount of paging activity. 


Chained I/O is used if the LEN operand is given a value in the range from 
2049 through 32768, or if BLKSIZE=(STD,n) is specified. 


The following special features should be noted with regard to chained I/0: 
e Procedure upon reaching end of file 


If end of file is reached during a read operation, UPAM transfers to the 
buffer only those PAM bLocks beLonging to the file. 


UPAM informs the calling job about the end-of-file condition as follows: 
- If eventing is not used: 


The user job receives control at the EXLST exit USERERR with error 
code X'0922' in the ID1ECB field of the FCB. 

The number of PAM blocks transferred is contained in the IDA1NBPP field 
of the FCB. If the value of this field is X'O0', all the PAM blocks to 
be read are Located outside the file. If the value of this field is 
greater than X'00', the user job must execute a wait operation if 

this was not implicitly contained in the read operation (i.e. in a 
RDWT operation). 


- If eventing is used: 


If all the PAM blocks to be read Lie outside the file, UPAM passes 
control to the user job at the EXLST exit USERERR with error code 
X'0922' in the ID1ECB field of the FCB. 

If at Least one of the PAM blocks to be read belongs to the file, UPAM 
causes either the continuation of the basic task or the initiation of 
a contingency task (see section 6.2.5). Now the IDECBNPA field of the 
FECB contains an indication as to the number of PAM bLocks that have 
been transferred. 


Contents of Meaning 
IDECBNPA 
= X'OO' ALL PAM bLocks to be read vere transferred to the 
buffer. 
= X'On' Only some of the PAM bLocks to be read belong to the 


file and were transferred to the buffer. 
The vaLue of IDECBNPA is the same as the number of 
these PAM bLocks. 


In the case of a WRT operation, a secondary allocation is performed; the 
specified PAM bLocks are appended to the file. 
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èe Locking and unlocking of PAM blocks 


Only the first of a series of PAM blocks to be Locked/unlocked need be 
specified in a PAM macro; the number of blocks to be Locked/unlocked is 
given by the operand LEN. 

It should, however, be noted that after a Lock or unlock operation, the 
file pointer points to the Last PAM block that vas Locked/unLocked. This 
block may Lie outside the file (see also above, "Procedure upon reaching 
end of five"). i 


e Processing of PAM keys 
There are two possible ways of processing PAM keys: 
- The user reads/writes each individual key of a series of PAM blocks 
(operand MKEY=YES3; KEYFLD must contain the address of a sufficiently 
Large area). 


- The user reads/writes only the first key of a series of PAM blocks. 


On writing, the following blocks are assigned the same key as the 
first block (the Logical block number is simply incremented by 1). 


6.2.4 Chaining of PAM macros in List Form 

The chaining of PAM macros is implemented by means of the following 

procedure: 

e The macros to be chained are to be generated in List form by means of the 
operand MF=L and accommodated in a constant area; chaining is effected by 


specifying the operand CHAIN-. 


Thus, the macros (except the Last) have the form: 


|ewment | PAM £ fcbaddr,operation,... ,MF=L,CHAIN=next-element 


In the case of the Last element in a chain, the operand CHAIN- is 
omitted. A chain of PAM macros in List form is called with a PAM macro 
having the following format: 


LN MF=(E,first-element) 


Only one SVC instruction is executed for each chain; i.e. the chaining 
. of UPAM requests avoids the overhead of a multiple SVC. The elements of a 
chain need not necessarily relate to the same file. 
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ixampLe of coding: 
START 
BALR 4,0 
PAM MF=(E,CHN1EL1) 
TERM 
*KONSTANTENBEREICH (= constant area) 
CHN1EL1 PAM eccceee sMF=L,CHAIN=CHNILEL2 
CHNAEL2 PAM eccceee sMF=L,CHAIN=CHN1IEL3 
CHN1EL3 PAM 4v. & MP SL | b 
END 


The following points should be noted with regard to the chaining of PAM 
macros in List form: 


If execution is successful, the user gains control at the statement 
following the PAM macro which requested processing of an operand List 
chain. 


ALL operations are carried out in exactly the same order in which the 

PAM macro Lists appear within the chain - with one exception: 

When the first operation which requests Locking is encountered, the rest 
of the chain is examined, and all operations which request Locking are 
registered. If it is impossible to implement alt the requested Locks 
within the available time, the chain is terminated at the operation which 
requested the first Lock. 


If any process which vas requested by an element in an operand List chain 
was unsuccessful, this process and all remaining processes of the chain 
(incLuding Locks) remain unexecuted; control is passed to the 

appropriate EXLST exit. 

At this point, register 1 points to the FCB of the file in which the 
error occurred. The error code (IDIECB) and the error byte (IDA1XITB) are 
set in this FCB as usual, and the IDACHERR field in the FCB is set to the 
address of the element of the operand List chain that caused the error. 


It should be noted that a CHK operation for an unfinished I/O operation 
also causes control to be transferred from the operand List chain to the 
user program at the address specified. The remaining operations in that 
chain (including Locks) remain unexecuted, and the IDICHERR field in the 
FCB is set to the address of the operand List element in which the CHK 
took place. It is therefore inadvisable to use check operations on 
operand List chains. 


It is the responsibility of the user to ensure that, within a chain, 
appropriate use is made of the Lock, read, vrite, wait, check and release 
Operations. Buffers and key fields are utilized by UPAM according to the 
request. A check is made to verify the existence of a buffer and for 
authorized access, but there is no guarantee that a buffer or a key field 
filled by an operation in a chain will not be overwritten by a Later 
operation of that chain. 
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A dummy program section (DSECT), which can be generated with the IDPPL 
macro, defines the format of the PAM operand List. 


In all cases where a chain of UPAM operand Lists cannot be fully pro- 


cessed (e.g. an operation failed, an error vas detected, a Lock could 
not be carried out, EOF was encountered, or CHK was issued for a current 
I/O request), the address of the first unexecuted chain entry is moved 
to the IDICHERR field of the FCB. It may be assumed that all preceding 
entries were executed correctly. 


There are two cases where UPAM cannot inform the user of errors via the 
FCB/EXLST facility: 


- The UPAM SVC is carried out and neither register 1 nor any chain 
operand contains a valid address (e.g. the address is not aligned on 
a word boundary, or the address describes a field which is not 
entirely part of the user's virtual storage space and is not Large 
enough to contain a UPAM macro operand List etc.). 


- The FCB address in the UPAM macro operand List is either missing or 
invalid. 


In these two cases, there is no FCB which could be informed of the error; 
UPAM therefore aborts the program. 


A complete UPAM operand List chain is declared valid before any process 
is initiated. Should either a CHAIN address or an FCB address be invalid, 
the job is aborted before any chain element is executed. 


If the eventing mechanism is used and there is no event item available 
at the end of the 1/0 operation to which the event can be reported, the 
user program is Likewise aborted. 
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6.2.5 Informing the User Job upon Termination of a UPAM 


1/0 Operation (Eventing Mechanism) 


Eventing with the specified macros is described below; for a more detailed 
description see the "Executive Macros" manuaL. 


Eventing is used by UPAM to report termination of a requested I/O to a 
job. 


The job can 


e be continued in parallel to the UPAM I/O operation and, when the 
anticipated event occurs (in this case, termination of the requested I/O 
operation), proceed vith a contingency task (asynchronous case). 


e wait for termination of the requested I/O operation and then proceed 
e (this type of processing is of course also possible without eventing). 


After completion of an I/O operation, UPAM issues a message to the 
associated event item (with the macro POSSIG). 
Sooner or Later this message will encounter the request issued by the user 


(SOLSIG). ; 
When both request and message are present (for the same event item), a 


contingency task is started or the basic task is continued, as the case 
may be. 


“UPAM processing” “Job” 


Initiation of a UPAM ΙΟ 
operation (PAM macro) 


€ 
Entry in the request 
Queues for queue (SOLSIG macro) 


Execution of the 


requested I/O 


message queue 
upon termination of 
the I/O operation 


task or continuation of 
the basic task 


Fig. 6-7: Coordination of user job and UPAM processing 
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Whenever this mode of processing is to be used, the following must occur in 
the basic task: 


e The system must be informed of the event item(s) and contingency 
definition(s) to be used (macros ENAEI, ENACO). 


The number of event items is equal to the maximum number of UPAM I/O 
requests simultaneously issued to the system (PAM macros with read or 
write function: = total of values from the FCB operand PAMREQS-). 


The number of contingency definitions depends on whether different 
procedures are required after execution of I/0 operations. If, for 
instance, the same procedure is always to apply, it is sufficient to code 
the contingency definition once only. 


€ A 14-byte control block (File Event Control Block, FECB) must be set up 
for each event item. 


e The correct value for the operand PAMREQS= must be specified in the FCB 
macro for each file; this corresponds to the maximum number of I/0 
operations requested simultaneously for that file. 


9 The address of the associated control block must be specified for each 
UPAM I/O request (operand FECB- in the PAM macro). No wait operations 
must be requested by the PAM macro, either explicitly or implicitly (see 
also the next point). 

The sequence of instructions READ ——» WRITE ——> WAIT for the same bLock 
thus produces an undefined result. The user must wait for the event 
(termination of the I/O operation) before issuing the WRITE call. 


e After each UPAM I/O request, precisely one request must be issued to the 
associated event item (SOLSIG macro). 


This request serves to determine whether the basic task is to continue in 
parallel to the I/O operation, or to wait for it to terminate. 


At the start of a contingency task, this task receives the following 
information in registers 2 and 3: 


Register 2 contains the event information code 
Register 3 contains in its three rightmost bytes the address of the » 
| operand List of the terminated operation (only with 


chained PAM macros) and in its. Leftmost byte the value 
X'10'. 


e The FECB must be aLigned on a vord boundary. 


e For a detailed description of eventing, refer to the "Executive Macros" 
manual. 


€ Until the first I/O operation with an FECB is terminated, this FECB must 
not be used for other 1/0 operations. 
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Format of the FiLe Event ControL BLock (FECB) 


Meaning of field Field name 
Internal code for event item 4 CBEVID 
Address of FCB 4 CBP1LNK 
Standard device byte 1 CBSDB 
Sense bytes 3 CBSDB1...3 
Executive flag byte 1 CBEFB 
Number of PAM blocks 1 CBNPA 


transferred 


Table 6-3: Format of the File Event Controt Block (FECB) 


The FECB can be provided with symbolic names by means of the IDECB macro. 


Structure of a contingency definition 


In a contingency task the user can respond to the various possibilities of 
1/0 termination. 


A UPAM I/O operation can be terminated in a number of different ways: 


= Normal 1/0 termination EFBzX*'80"' 
= I/O operation Led to special condition EFB=X' C0" 
= UnrecoverabLle error EFBZX*'AO' 


(e.g. hardvare error) 
(EFB = Executive flag bytes; see FECB) 


Multiple branches must be provided in contingency definitions to accommoda 
the different cases above. | 
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=zxample: 


The example illustrates the possibilities offered by eventing with UPAM. 


The program gives rise to the following actions: 


1. 


2ο 


3. 


9. 


Open input file and prepare for eventing. 

Start UPAM input operation. 

Make entry in event item's request queue. e | 
Execute program Loop vithout end condition; count executed Loops. 


Interrupt Loop and start contingency task when input operation has 
terminated. 


Load program counter of interrupted basic task vith a continuation 
address outside the Loop. 


Terminate contingency task and continue basic task. 
Output number of executed Loops. 


Terminate eventing and close file. 


The above numbering is used in the following source program, with the 
exception of action 5, which is performed by the operating system. 


The program performs actions 2 through 8 ten times in an outer Loop (Loop 
counter is register 5). 
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UPAMPRO START 
PRINT NOGEN 
BALR Se? 


»4 


LH 5,-H'10' 


OPEN UPAMDAT, INPUT 

ENAEI EINAME-EINGABEOPENDE, EIIDRET-ESTBLOCK 

ENACO CONAME-LADENBEFEHLSZAEHELRBASPROZ, * 
: COIDRET=COKUKEN, COADAD=ADRCONTI 


* 
STARTEA PAM UPAMDAT,RD,FECB=ESTBLOCK,HP=1 
ANFORD Hd guy EIID-ESTBLOCK,COID-COKUKEN 


6, 


X 
SCHLEIFE AH 6,-H'2' 


1 
T B SCHLEIFE 


NACHCON CVD 6,ANZAHL 

UNPK ANZAHL1,ANZAHL 

MVZ . ANZAHL1*15(1),20NE 
WROUT MELD,TERM,MODE-LINE 
BCT 5,STARTEA 


DISEI EINAME-EINGABEOPENDE 
CLOSE UPAMDAT (9) 
TERM TERM 
κ 
CONTIN BALR 4,0 
L 6 , ADNACHCO .. © @ 
CONTXT PROCESS=MAIN, FUNCT=WRITE, 
ACKR=(PC) , DINRz C6) 
3 RETCO | 
x KONSTANTEN UND STEUERBLOECKE 
ANZAHL DS D 
MELD DC AL2(MELDEND-MELD) 


DC X'404001' 


ANZAHL1 DS CL16 
DC "SCHLEIFENDURCHLAEUFE' 
τοσο εου x 


COKUKEN DS F 
ADRCONTI DC ACCONTIN) 
ADNACHCO DC ACNACHCON) 
ESTBLOCK DS 4F 
UPAMDAT FCB  FCBTYPE=PAM,LINK=EIN, * 
IOAREA1-EINBER,IOAREA2zNO 
ZONE DC X'F0' 
LTORG 


κ K X X X 


EINGABEBEREICH 


ORG UPAMPRO+2048 
EINBER A CL2048 
N 


FILE UPAMPRO.EIN,LINK=EIN,FCBTYPE=PAM | 
EXEC X 


* P001 -DLL V-725 

X P500 UPAMPRO/001/82-02-05 LOADED 
0000000000019268SCHLEIFENDURCHLAEUFE 
0000000000026457SCHLEIFENDURCHLAEUFE 
0000000000024323SCHLEIFENDURCHLAEUFE 
0000000000018992SCHLEIFENDURCHLAEUFE 
0000000000025732SCHLEIFENDURCHLAEUFE 
0000000000025857SCHLEIFENDURCHLAEUFE 
0000000000020617SCHLEIFENDURCHLAEUFE . 
0000000000026101SCHLEIFENDURCHLAEUFE 
0000000000029053SCHLEIFENDURCHLAEUFE: 
0000000000013818SCHLEIFENDURCHLAEUFF 


(ANZAHL = number; KONSTANTEN UND STEUERBLOECKE = constants and control 
bLocks; SCHLEIFENDURCHLAUEFE - executed Loops) 
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6.2.6 GeneraL Programming Notes 


e Since a block is not transferred to the user buffer until an explicit 
action macro has been issued, a delay is caused. 
Consequently, an asynchronous I/O operation must be terminated with the 
WT action macro. In the case of P1 eventing, the SOLSIG macro should be 
used (synchronously or asynchronously). 


e For every unsuccessful branch to the UPAM routines, control is trans- 
ferred to the routine specified in the EXIT operand of the FCB, or to 
the corresponding EXLST routine. An identifier is stored in the FCB. 


e Whenever UPAM causes program termination, it places the address where the 
termination occurred in register 0; the address of the UPAM operand List 
chain eLement in which the error vas detected is placed in register 1; 
and the UPAM error code is placed in register 15. Thus it is easy to 
Locate this information in the printout of the memory dump. 


If register 1 contained an invalid address at the time when the PAM macro 
vas executed for the first time, register O of the memory dump will 
contain that invalid address, and register 1 in the memory dump will 
contain zeros (i.e. the error occurred before the first eLement of the 
operand List chain vas Located). 


e The five EXLST addresses used by UPAM are: 
ERRADDR Hardware error or abnormal I/O termination 


USERERR Invalid use of macro in the program or attempt to read a 
PAM bLock not belonging to the file (EOF) 


EOFADDR Attempt to read a *DUMMY file — 
PGLOCK Not all of the requested Locks are available within the given 
period of time, and the job has not currently Locked any 
blocks. 
DLOCK Attempt to read a Locked block, or request for an additional 
Lock. 
€ PAM blocks which have been allocated to a file, but which have not yet - 


been written by the owner of this file are identified by their internal 
file names (bytes 1 through 4 in the PAM key), which do not correspond to 
the current internal file name. 

Comparison must be performed by the user, who must bear in mind that: 


- At OPEN time, the current internal file name is written to the first 
word in the IDIKEY1 field of the FCB. 


- After execution of a RDWT operation, the internal file name of the 
block read is Located in the first word of the FCB field ID1KEY2. 


- After execution of one of the operations LRD, LRDWT, RD, WRT, WRTWT or 
WRTWU, the internal file name of the PAM bLock concerned is Located in 
the first word of the FCB field ΙΡΙΚΕΥΙ. The entry generated by OPEN 
is overwritten, but should be saved prior to processing for subsequent 
comparison. 


- See also the KEYFLD operand in the PAM macro. 
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e The 1Ι01ι ΜΒ field in the FCB is used to store the address of the Last 
buffer on which a WT operation was carried out successfully by UPAM. The 
highest-order byte is used as an indicator. If the Last UPAM operation 
directed to the file vas a successful WT (either explicit or implicit; in 
the Latter case, irrespective of the success or othervise of the operation 
which initiated that WT), then the highest-order byte of IDI1LWB assumes 
the value X"00", and the three Low-order bytes contain the address of the 
buffer to which the WT referred. 


On the other hand, if the Last UPAM operation on that file did not cause 
a WT, the highest-order byte of ID1LWB is set to X'FF', and the remaining 
three bytes are vithout significance. ; 


The request to Lock the bLock had to be rejected and the user program 
itself has already Locked the block. 


6.2.7 UPAM Record Format 
UPAM operation is bLock-oriented. The physical data blocks aLvays have a 
Length of n*2048 bytes (where n = 1,...,16). 


If the operand LEN- in the PAM macro has a value not equal to n*2048 
(where n = 1,...,16), then: 


- in the case of a write operation, the Last PAM block to be written is 
filled with binary zeros. 


- in the case of a read operation, the Last PAM bLock to be read is not 
transferred to the buffer. 


ExampLe: 
Let the operands WRT and LEN=4000 be specified in the PAM macro. 


4000 bytes are transferred from the buffer, 96 bytes containing X'OO' are 
appended, and 2 PAM bLocks are written to the file. 


1st PAM bLock 2nd PAM bLock 
2048 bytes from buffer 1952 bytes from buffer 96 bytes Χ'ΩΩ" 
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6.2.8 PAM Keys 


Each PAM block is allocated a 16-byte key (PAM key). 
The PAM key has the following structure: 


- Bytes O through 3 contain the internal file name (coded file ID) of the 
file to which the PAM bLock belongs or Last belonged. 
The DMS establishes the internal file name on the basis of a number of 
factors including the file creation date. This provides for unambiguous 
differentiation between different files. 


- Byte 4 contains the version number which the file had when the block 
was Last processed. 
This byte is evaluated and/or updated by the DMS or ARCHIVE when the file 
is created, updated, deleted or formatted. 


- Bytes 5 through 7 contain the Logical block number of the PAM block. 


- Bytes 8 through 15 contain different information depending on the access 
method used. UPAM does not utilize this fields nevertheless the user 
should not use these bytes. 

ISAM and SAM need this field. Further details may be found in sections 
6.3.8, "Use of PAM Keys in ISAM", and 6.4.4, "Use of PAM Keys in SAM". 


Note: 
Certain disk types are initialized with 512-byte blocks without a separate 


field for the PAM key. For this reason UPAM users are advised to stop using 
the PAM key. 
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6.2.9 UPAM Macros 
The following macros exist for UPAM: 
€ ALL service macros (e.g. OPEN, CLOSE, FCB) 
» The PAM macro, which includes the following operations: 
CHK check the status of I/O processing 
LOCK Lock a PAM bLock 
LRD Lock a PAM bLock and read the contents into main memory 
LRDWT same as LRD; vait for I/O compLetion 
RD/RDWT read a PAM block into main memory and optionally wait for 
© I/O compLetion 
SETL set the file pointer for further execution of a job 
UNLOCK unlock a PAM block 
WRT/WRTWT write data from main memory into a PAM block and optionally 


wait for I/O completion 


WRTWU write from main memory into a PAM block, wait for I/O 
compLetion, subsequently unlock the PAM bLock written 


WT wait for completion of an 1/0 operation 


e If eventing is used in conjunction vith UPAM, the following macros are 
avaiLabLe (the macros highlighted in bold type are mandatory; see also 
section 6.5.2, "Informing the User Job upon Termination of a UPAM I/O 
Operation"): 


ENAEI allocate an event item to a user job 
DISEI deallocate a user job from an event item 
- CHKEI check the status of an event item 
SOLSIG send a request to an event item 
ENACO enabLe a contingency definition, i.e. allow it to control 


contingency tasks 


DISCO nuLLify a contingency definition, i.e. prohibit it from 
controLLing contingency tasks 


LEVCO change the priority Level of a contingency task or the 
basic task 


RETCO terminate a contingency task 

CONTXT provide read or write access to the register set and 
program counter (the "context") of an interrupted 
contingency task or the basic task 


These macros are described in the "Executive Macros" manuaL. 
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FCB CREATE FILE CONTROL BLOCK «TYPE 0» 


Operation Operands 
FCB FCBTYPE=PAM 


NO NO 
C,LINK=Linkname] Ε,αολΗεΑ1-| h Cs TOAREAZ=| h 
reLexp relexp 


(relexp) STD 
[ ,EXIT- ] L,BLKSIZE- ] 
relexp (STD,absexp) 


YES 
[,PAMREQS=absexp] L,PAMTOUT-absexpl {/SHARUPD= NO h 


WEAK 
INPUT 
Γ,ΟΡΕΝΞΙΙΝοΟυΤΙΙ L,FILE-fiLenamel [,PASS=password] 
OUTIN 


YES 
C,RETPD=days] L,WRCHK- J 


NO 
code 
C,OPTION= 
code,code) 


See chapter 5 for a description of the operands. 


Notes: 


The RECFORM and RECSIZE operands can be specified, but are ignored by the 
UPAM action macro. 


However, the BLKSIZE operand is required: 

- if the operands IOAREA1 and/or IOAREA2 have not been specified in the FCB 
macro. In this case, the system reserves buffer areas. The buffer size 
corresponds to the value specified for BLKSIZE in the FCB macro. 

- if the operands IOAREA1-reLexp and/or IOAREA2-reLexp have been specified 
in the FCB macro. In this case, the buffer sizes are checked when the 
file is opened. 


In either case, the value of the LEN operand in the PAM macro must not 
exceed the vaLue of the BLKSIZE operand in the FCB macro. 


Exception: 


If an I/O area is specified explicitly in the PAM macro (operand LOC- 
reLexp), the BLKSIZE operand in the FCB macro is irrelevant. 
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PAM 


PAN PERFORM UPAM ACTIONS «TYPE 5) 


ALL user requests to the DMS for UPAM actions are made using this macro. 


Operation 


PAM 


fcbaddr 


CHK 


LOCK 


CRD 


LRDWT 


SETL 


Operands 
fcbaddr 


CHK 

LOCK 

LRD 

LRDWT 

RD 

absexp 

E 1 [,CHAIN=relexp] [,FECB=relexp] [ «neo [*absoxpla 

SETL -absexp 
UNLOCK 
WRT 
WRTWT 
WRTWU 
WT 


SID 1 
C,KEYFLD=relexp] L,LEN- J L,LOCz212 1 
absexp relexp 


YES 
C,MKEY= ] [£,REQNO=absexp] 


NO 


. This operand aulici i uh the address of the FCB (reLexp) 
associated vith the five. 


This operand checks vhether the specified I/0 request has 
been completed. If so, the program proceeds. Otherwise, 
control is transferred to the address specified by the LOC 
operand in the user program. 


This operand Locks PAM blocks (see also the operand HP=). 


As for LOCK; if Locking was successful, processing continues 
as for RD. 


As for LOCK and LRD; if Locking was successful, processing 
continues as for RDWT. 


This operand initiates the reading of a data block from the 
file into main memory; the job continues immediately after 
the read operation has been initiated. 


As for RD, with the difference that the job does not 
continue until the read operation has been completed. 


This operand causes the file pointer to be set to the PAM 
block specified. 
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UNLOCK 


WRT 


WRTWT 


WRTWU 


WT 


CHAIN= 


FECB= 


6-30 


This operand causes Locked PAM blocks to be unlocked (see 
also the operand HP=). 


This operand initiates the writing of a data block from 
main memory into the file; immediate continuation of the 


job. 


As for WRT, with the difference that the job does not con- 
tinue until the write operation has been completed. 


As for WRTWT; immediately after completion of the I/O 
operation, the PAM block just written is unlocked. 


This operation causes the program to wait for the end of a 
particular request. The program continues upon completion 
of this request. | 
This operand specifies the symbolic address of the next 
eLement in a chain of PAM macros in List form. 
must not contain more than 255 eLements. 
Default vaLue: 

The List is regarded as the Last element in a chain. 

This operand specifies the symbolic address of a File Event 
Control Block (see section 6.2.5). If this operand is 
specified, the REQNO operand must be omitted. 

This operand references a PAM block, nameLy: 


= in the case of non-chained I/O, the PAM bLock to be 
transferred (or Locked). 


- in the 
bLocks 


There are 


- Direct 
number 


- Specification of a relative Logical block number. 


*absexp 
HP= 


-absexp 


Relative Logical block numbers relate to the file 


pointer. 


The absolute Logical block number is computed as the sum 
of the file pointer and the specified relative block 


number. 


Default value: 


Such a chain 


case of chained 1/0, the first in a series of PAM 
to be transferred (or Locked). 


two methods of referencing a PAM block: 


specification of the absolute Logical block 
(HP=absexp). 


+ 1 (i.e. sequential processing) 
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Programming notes: 


- The first PAM block of a UPAM file is number 1. At the 
time a UPAM file is opened, the file pointer is set to 
an initial value of 0. This operand is ignored in WT or 
CHK operations. WT and CHK relate to 1/0 requests and not 
to PAM blocks. 


- Any operation (except WT and CHK) not causing a branch 
to an error recovery routine has the effect that the 
file pointer is set to the number of the PAM bLock vhich 
is being accessed. This is also true of Locking/ 
unlocking even if SHARUPD=NO is specified. Normally, 
however, the file pointer remains unchanged if 
operations result in an error routine instead of being 
completed successfully. 


- If n denotes the number of PAM blocks already allocated 
to a file and k is the value of the secondary 
allocation, the following rules must be observed: 


RD HP can define only a PAM block which has a 
RDWT number from 1 to n. 

LRD 

LRDWT 

WRT HP can define only a PAM bLock which has a 
WRTWT number from 1 to ntke 

WRTWU Whenever a PAM block of any number from n*1 to 


n*k is encountered, secondary allocation takes 
place automatically, the size of the file being 
extended to ntk PAM bLocks. 


If a number of consecutive PAM bLocks are to 

be written with one PAM macro (chained I/0), 
storage space for all blocks to be written must 
be allocated (at the Latest) after a single 
secondary allocation. 


Thus, the following must apply: 


(block number of Last block to be written) 
< ntk 


: LOCK HP must specify a Logical block number greater 
UNLOCK than zero. This enables the Locking and 
unlocking of PAM blocks which are currently not 
allocated. Such Locking/unLlocking does not 
Lead to secondary allocation. 


KEYFLD= In the case of non-chained I/0, this operand specifies the 
address of a 16-byte area, into which the PAM key is placed 
during reading or from which it is taken during writing, as 
the case may be. 


In the case of chained I/O and the processing of all 
associated PAM keys (operand MKEY=YES), this operand is 
mandatory and must contain the address of a sufficiently 
Large area (number of PAM blocks to be transferred 
multiplied by 16 bytes). 
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If only the PAM key of the first of a series of PAM blocks 
is to be processed (MKEY=NO), the conditions stipulated 
above for non-chained I/O apply; in this case, the KEYFLD 
operand can optionally be omitted, whereupon the default 
value will take effect. 


DefauLt value: 


For all read and write operations, usually the address of 
the IDIKEY1 field in the FCB. Exception: for the RDWT 
operation it is the address of the IDIKEY2 field in the 
FCB. 


Programming notes: 


- If a WT is issued for a successful read operation, 
either explicitly or implicitly, the 16-byte PAM key 
assigned to the block read is moved to this field A 
CHK operation issued following the end of an I/O 
operation has the same effect as a WT operation. 9 


- In awrite operation, if a user places any information 
in the Last 8 bytes of the 16-byte field defined by this 
operand, that information is written to the file as part 
of the PAM key which is assigned to the PAM bLock to be 
written (not recommended). UPAM generally creates the 
first 8 bytes of this field before the write operation 
begins. 


- This operand is ignored by the WT, CHK, LOCK, UNLOCK 
and SETL operations. 


LEN= This operand specifies the Length of the I/O buffer to be 


The value of this operand can be in the range 
1 through 32768. 


Two cases should be distinguished: 
- 1 < LEN < 2048 


In this case, one PAM bLock is read or written with each 
PAM macro. 


- 2049 < LEN < 32768 
In this case, chained I/O is used. 


The number of PAM bLocks to be transferred is determined 
from the value of the LEN operand 85 follows: 


If LEN is an integer multiple of 2048, the quotient of 
(LEN / 2048) gives the number of PAM bLocks to be 
transferred. 


Othervise, the quotient is rounded up to the next higher 
integer. 
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Notes: 


- The LEN operand is ignored by the WT, CHK and SETL 
operations. 


- See also section 6.2.9, FCB macro for UPAM, operand 
BLKSIZE. 


LOCz This operand references the I/O buffer in main memory 
(though not in the case of CHK). The buffer must be capable 
of holding at Least as many PAM blocks as are specified by 
the value of LEN. If the buffer is Less than or equal to 
4096 bytes (one page), it must be fully contained on one 
page and be aLigned on a vord boundary. If this area is 
Longer than one page, it must: 


1. begin on a page boundary 
2. be virtually contiguous 


e 5. not cross a segment boundary 
=1 The buffer address is in FCB field IOAREA1. 
=2 The buffer address is in FCB field IOAREA2. 
-reLexp This operand specifies the buffer address or, if a checked 
I/O request has not yet terminated, the continuation 
address. 


Default value: 


The IOAREA1 address in the FCB, provided this vas not the 
Last buffer address or the IOAREA2 address does not exist. 


The IOAREA2 address in the FCB in all other cases. 
Notes: 
- In the case of the CHK operation, the LOC operand must 


not be omitted; in fact, the following specification is 
mandatory: 


e LOC=reLlexp 


- This operand is ignored by the operations WT, LOCK, 
UNLOCK and SETL. 


- Wherever possible, the data buffers should be aligned on 
a 2 KB word boundary. They must be aligned if the address 
is greater than X'800'. This eliminates the need for 
intermediate data buffering under certain circumstances, 
and the resultant deterioration in performance. 


MKEY= This operand is significant for chained 1/0 onLy. 


=YES PAM keys are expected by the user for each PAM bLock 
read, or provided by the user for each PAM block written. 


=NQ Only the PAM key of the first of a series of PAM blocks 
is expected/provided by the user. 
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REQNO= 
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This operand specifies the number of the I/O request 
assigned to this operation. If this operand is 
specified, the FECB operand must be omitted. 


Default value: REQNO=1 


Notes: 


This operand can have only values from 1 to n, where n 
is the value of the PAMREQS operand in the FCB. 


This operand is ignored by the LOCK, UNLOCK and SETL 
operations. For the WT and CHK operations, this is the 
way of specifying the I/O request for which the 
operation is to be carried out. 


Each request number can be assigned one asynchronous 
1/0 operation only. The end of this asynchronous 1/0 
operation is to be waited for: this can be specified 
either explicitly by supplying its request number in a 
WT operation, or implicitly by another read or write 
operation for the same request number. If an error is 
encountered during an implicit wait for the end of an 
I/O request, error code 997 appears, and the request 
which caused the implicit WT is not carried out. 


Request numbers are system resources; improper 
use may impair the efficiency of the system. 
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6.2 ISAM «INDEXED SEQUENTIAL ACCESS METHOD» 


ISAM processes Logical records in an indexed-sequential file. It may be 
used to: 


- Create an indexed=-sequential file in a sequential or non-sequentiaL 
manner. 


- Retrieve the Logical records in the file in a sequential or 
non-sequentiaL manner. 


- Update records in a sequential or non-sequential manner. 


- Insert new records in a file on the basis of their Logical order in that 
five. 


- Delete selected records from the file. 


- Retrieve the next sequential record in a file which contains the 
requested flags. 


Transfer of data to and from the fiLe can be in either of two modes: 

Move mode: The user specifies the address of the record in his 
program. The system is responsible for transferring 
data to or from the buffers. 

Locate mode: The user requests the address of the current record 
in the buffer area. The user is responsible for 
transferring data to and from the buffers. 


The following action macros are available in iem to control file 
processing: 


ELIM Eliminate a record from the file. 


GET Retrieve the next record in the file in ascending 
sequential order of the record keys. 


GETFL Retrieve the next Logical record that satisfies the flag 
criterion. 
GETKY Retrieve the next record on the basis of a specified 


record key. 


GETR Retrieve the next record in the file in descending 
sequential order of the record keys. 


INSRT Insert a new record in the file in the position determined by its 
record key. 


ISREQ Unlock a data bLock. 
OSTAT Provide information about opened files (e.g. co-users). 
PUT Add a Logical record at the end of the file. PUT is normally used 


for the initial creation of a file, the Logical records then being 
written in ascending sequential order of their record keys. 
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PUTX Write a record prevzouaty read by GET, GETR, GETFL or GETKY back 
into the buffer. 

RETRY betes an I/O operation, reposition a block or wait for it to 
be unlocked after the PGLOCK exit of the EXLST macro has been 
taken. 

SETL Specify the position in the file at which subsequent pro- 
cessing is to begin. The beginning of the file, the end of 
the file, or the Location of a record with the designated key can 
be specified. 

STORE Place a new record in the file or replace an existing record; 

the position is determined by the record key. 
6.3.1 ISAM File Structure | 9 


An ISAM file consists of data and index blocks. Data blocks are n*2048 

bytes in Length, where 1 < n < 16. Index blocks have a usable Length of 

2044 bytes. 

The entries in the data blocks contain the user's Logical records. Entries 
in the index blocks contain pointers either to the index blocks of the Lover 
Levels or, if it is the index block of the Lowest Level, to the data blocks. 
For each data block of the file there is, at the Lowest Level, an index 
entry of the Length KL+4, where KL corresponds to key Length (+ Length of 
flags where applicable); the highest key contained in the data block is 


marked. 


The index entries are always sorted in ascending order of the record keys. 


The data blocks, also referred to as Level-0 blocks, contain the Logical 
records arranged in ascending sequence of the record keys. | 


Highest index level 
(in this case level 3) 


p ος 54 Index blocks, level 2 


Intermediate 


levels Index blocks, level 1 
(in this case the 


Πω. μι ties 


ne * T ME pH be E Date blocks, level 0 


Fig. 6-8: ISAM file structure (in diagram form) 
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The highest Level index block is always present in the file, even if it is a 
null file, i.e. contains no records. In addition to pointers, this index 
block contains 36 bytes of ISAM Label information, which is used internally 
by ISAM. Therefore, in the calculations that follow, the usable Length of 
the highest Level index block is considered to be 2008 bytes rather than 
2044 bytes. 


In the case of Smaller ISAM files, one index Level is usually sufficient. In 
this case, the block of the highest index Level is at Level 1 and contains 
pointers to the data blocks. 


Whenever a file grows so Large that the highest Level index block no Longer 

has enough space to accommodate pointers to all of the blocks on the next 

Lower Level, that block is split in half and an index block is created, one 

Level higher than the old one and containing two pointers, one to each half 

of the split block. The two blocks generated from the original index block 

are Linked. b 


- Notes: 


- By Linking index blocks of the same Level, only 2044 bytes remain 
available as of Version 7.5, since the Last 4 bytes in the block are 
reserved for Linking. 

Existing files can be processed without any problem. The Last four bytes 
are not used before processing, and then only until the next higher 
index Level has been altered. 


- Elimination of the PAM keys, which is required as a result of the new 
disk devices, necessitates a change in the format of ISAM files; in 
particular this means that the area available for records on each PAM page 
has been reduced. 


Recommendation: The maximum record Length for ISAM files should not 
exceed "n*2000 bytes" when BLKSIZE=(STD,n) is specified. Use of 
records with a Length of "n*2048 bytes" is still possible, but this 
will have an adverse effect on performance. 


- 6.3.2 ISAM Record Format 


ISAM supports two record formats, as follows: 
F (fixed Length) 
V (variable Length). 


The block size can be n*2048 bytes, where 1 < n < 16. The buffer size must 
correspond to the block size and must be a multiple (max. 16) of the 
Standard size. The key must be contained at a fixed position within the 
record and be the same size for each record in the file. See section 6.1.3 
for the format of Logical records. 
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6.3.3 Opening an ISAM File 
ISAM files can be opened in the following modes: 


INPUT To retrieve records from an existing file. The records may be 
retrieved sequentially or randomly. 


OUTPUT To create a new file. 

EXTEND To add records to the end of an existing file. 

INOUT To retrieve, delete, replace and insert records in an existing 
file. 

OUTIN To retrieve, delete, replace, insert and store records in a 
new file. 


Table 6-4 summarizes the ISAM processing applicable to each OPEN mode. 


Action 
macro 


Table 6-4: ISAM action macros in relation to OPEN modes 

Where: 

M action macro: functions in move mode (also allowed in Locate mode 
if the work area was supplied with data) 

B action macro: functions allowed in move or Locate mode 

X action macro allowed 

If there is no entry in the table, the action is not allowed. 


Overlap buffering of I/O operations is supported for all OPEN modes. 
Buffering is optional for the GET and GETR action macros. 


These macros do not require the supervisor call instruction (SVC) until all 
the Logical records in the current buffer have been processed. 
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If this Look-ahead buffering is not desired, the programmmer should 
specifically omit the OVERLAP operand from the FCB. If buffering is per- 
formed and the program switches from forward to reverse processing, or 

from sequential to random processing, the 1/0 operation which is to ready 
the next sequential buffer is initiated immediately. This can result in an 
uncompleted operation because, if processing was exclusively sequential, the 
System supplies data which is not accessed. 


PUT operations are always overlapped. 


If the padding factor (PAD=) is specified, space is reserved only in the case 
of sequential creation of the file via the PUT action macroe The INSRT and 
STORE action macros attempt to use all the Space available in a data block. 


While a file is open, the KEYLEN and KEYPOS fields in the P1FCB have a value 
of n-1. If the file contains fixed-length records CRECFORM=F), the value of 
the KEYPOS field is (n+4)- 1 = n*3. In both cases the value of the KEYPOS 
field is contained in either the catalog entry or the FCB macro or FILE 


e command. 


Note: 

When opening a new ISAM file a new value is calculated for the BLKSIZE 
field in the Ρ1ΙΕΟΒ. The PAD value from the FCB is taken into account. The 
value calculated (specified in BLKSIZE - PAD) is then stored in the BLKSIZE 


field. 
This does not apply to INPUT processing. 


ExampLe: 


Value BLKSIZE=(STD,3) 
PAD=15 (default value) 


The value of the BLKSIZE field during processing is X'1467'. 
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6.3.45 Flagged ISAM Files. 


Flags enable the user to make use both of the ISAM key and of other record 
attributes in order to qualify and accelerate access. There are two types of 
flag: value flags and Logical flags. Flagged ISAM files may contain 

either value flags, Logical flags or both. 


The flag is part of the user's Logical record; the value flag immediately 
follows the key, and the Logical flag immediately follows the value flag Cor 
the key, if there is no value flag). 


User record 


Flag area 


κ μα ο ae a 


Index area ` τ 


The only restriction on key Length, value Length and Logical Length is that 
their total Length must not exceed 255 and the key Length must be at Least 
1. 


Flag information is propagated throughout all index Levels of the ISAM file. 


Value information in the index entries is created on the basis of the value 
specified by the user in the VALPROP=operand. 


If the MAX (MIN) function is specified, /each index entry will contain the 
highest (Lowest) value flag of the next Lower Level block (either data or 
index block) to which it points. Whether propagation of the maximum or 
minimum value flag has any point depends on'the vay in which the records are 
subsequently to be made available. The usefulness of a value flag is all the 
greater the more evenly the value flags rise or fall with an ascending ISAM 
key (see example below). 


Opening a flagged ISAM file: 


If either VALLEN or LOGLEN is not equal to zero, the file is assumed to be 
flagged. If the file already exists (the OPEN mode is INPUT, INOUT or 


oy EXTEND), the catalog values of VALPROP or VALLEN are used. LOGLEN must 


always be specified when the file is created with a flag area. The catalog 
values cannot be changed by the FCB macro or FILE command. 
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Example: 


Personnel file, value flag = year-of-birth, VALPROP=MIN 
Thus: 


From each data block, the earliest year-of-birth value for the employees 
contained therein is transferred to the index block. 


1. Suitable search query; 

Retrieve all records for employees born before 1950. 
Ze Unsuitable searcifquery: 

Retrieve all records for employees born after 1950. 


In the first case, whole data blocks can be skipped immediately because 
of the value flag. 


ISAM 


In the second case, every record in each block must be checked. Here a file 


with VALPROP=MAX would be advisable. 


In the Logical flag it is possible to code, in bit form, dual attributes of 
the object described in the data record. ALL Logical bytes of a data block 


(or index block) are then Linked by means of Logical OR and passed on to 
the (next higher) index entry. In searching for records with particular 
attributes, the DMS can then decide, on the basis of knowing the index 


entry, whether records with these attributes are present in the referenced 


bLock. 
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6.35.5 ISAM Shared File Update 


Under ISAM a file can be updated by several users at the same time. This 
support is based on two principles: 


Shared file update is defined by the user at file OPEN time. To avoid 
conflicts which may arise if several programs attempt to access and update 
the same data block, a mechanism is provided to allow the user to Lock/ 
unlock data blocks. If the Lock/unlock function has been omitted, and it is 
necessary for the data block to be Locked, this function is carried out 
automatically by ISAM. The following paragraphs describe in detail the 
shared update facilities available to the user. 


Opening an ISAM fiLe 


The first user to open an ISAM file can open it with any combination of the 
values permitted for OPEN and SHARUPD. The following table indicates which 
OPEN/SHARUPD combination will be permitted when user B tries to open the 
file which user A has already opened. If more than one user has already 
opened the file, the OPEN/SHARUPD combination of user B will be compared 
with the OPEN/SHARUPD combination of every user who has opened the file; 
user B can open the file only if each such comparison permits him to do so. 


USER B 


SHARUPD=YES SHARUPD=NO 


EXTEND 


JUCA O 


OUTPUT 


m< il 


EXTEND 


OUTPUT 


οσο ος ο ὸῬτόώ 


Table 6-5: Processing an ISAM file in shared update mode 
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ISAM action macros 


If a file is updated by more than one user, it is absolutely mandatory for 
parts of the file to be Locked, so as to prevent more than one user from 
accessing and updating the data block at the same time. This blocking is 
performed at data block Level. Some of the ISAM action macros (e.g PUT, 
STORE, INSRT, ELIM (with KEY)) already contain all 3 functions; i.e. the 
macro Locks, updates and unLocks the data bLock concerned. 

With the other macros, tvo macros are required to carry out these functions: 


e GET, GETR, GETKY or GETFL macro to Lock the block. 
e. PUTX or ELIM (without KEY) macro to update and unlock the block. 


An optional LOCK/NOLOCK operand may be specified for the GET, GETR, GETKY 
or GETFL macro. 


If a data bLock has been Locked by GET, GETR, GETKY or GETFL vith the LOCK 
specification, other users can read the block (e.g. vith SETL or vith GET, 
GETR, GETKY or GETFL vith the NOLOCK option), but they cannot update it; 
i.e. they cannot Lock it by specifying LOCK in a macro. If NOLOCK is 
specified, other users can read, Lock, update and unlock the data block. 


If SHARUPD=NO is specified, the LOCK operand is ignored in the GET, GETR, 
GETKY or GETFL macro; the data block is not Locked. 


Note: 


In this system version, registers 0, 1, 14 and 15 are not destroyed by all 
of the action macros. The user should not, however, assume that this is 
always the case, since registers 0, 1, 14 and 15 will be destroyed by every 
action macro in all future subsequent versions. 


Use of the LOCK/NOLOCK operand with SHARUPD=YES 


A data block which has been Locked by one user can be read but not updated 
by other users. Furthermore, it is not possible for two users to Lock the 
same block simuLtaneousLy. 


On the other hand, a user who is reading a data block but has not Locked it 
permits other users to read and update the block. 


Consequently, the use of NOLOCK in the GET, GETR, GETKY and GETFL macros can 
be seen as extending the degree of data block shareability. However, LOCK 
must be specified if the data block is to be updated via a PUTX or ELIM 
macro (without KEY) or if the user wants to ensure that no other user will 
update the data block while he is reading it. 


Locking data blocks 


A user can have more than one ISAM file opened with SHARUPD=YES but he 
cannot Lock more than one data block at a time. 


The Locking of data blocks is conceived as follows: the first step under- 
taken by every ISAM action macro which is to Lock a data block is to unlock 
any data block this user has Locked in any file. Moreover, every ISAM action 
macro will unlock any Locked data block in the file for which the macro is 
issued. However, GET, GETR and PUT will not actually unlock the data block 
if the same data block is to be relocked Later in the macro processing; PUTX 
and ELIM (without KEY) do not unlock the data block until updating has been 
compLeted. 
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Implicit Locking and unlocking of data blocks 


Data blocks can be explicitly Locked by the GET, GETR, GETKY and GETFL 
macros and unlocked by PUTX and ELIM (without KEY). In addition, however, it 
is possible for every action macro to be able to Lock/unLock certain data 
blocks implicitLy. 


If SHARUPD=YES is specified, the appropriate data block is Locked before it 
is updated by STORE, INSRT or ELIM (with KEY) and then unlocked again. 


In order to avoid deadlock situations, each user can Lock only one data 
block, regardless of how many files he has opened. This is ensured in the 
following way: whenever the user issues an action macro to Lock a data 
block, the data block (of any file) previously Locked by the user is 
unlocked. This happens, for example, if the file is opened with SHARUPD=YES 
and the macros STORE, INSRT and ELIM (without KEY) have been issued, or the 
macros PUT, GET, GETR, GETKY and GETFL with the LOCK specification were 
used. 


If a PUT macro is issued for a file opened in Locate mode, IOREG is updated 
and the appropriate data block is Locked. 

The user must move the record to the Location defined by IOREG (MVC). 

The block is not unlocked until it is complete, or until another action 
macro has been issued. 


If a record is modified, rewriting takes place with PUTX. However, the 
block is not stored until an action macro is issued to access another block. 
Until this occurs, the block remains Locked. 


Updating a data block 


Before a data block can be updated, it must be Locked. 

When the update is complete, a check is made as to whether the index blocks 
have to be updated. If this is the case, the index block is Locked and 
modified. Index and data blocks are unLocked once they have been updated and 
the next higher user Level has been Locked. 


error exits 
LOCK exit: i » 


If the OPEN/SHARUPD entries make it impossible to open the file, or if 
probLems occur when opening a file already opened by other users, control is 
transferred to the user at the LOCK exit. 


USERERR exit: 


This exit is taken when action macros are wrongly used (e.g. PUTX without a 
preceding GETKY). 


The user may also be given control at this exit if he has issued a GET, GETR 


or GETFL macro after the PGLOCK exit was taken without first repositioning 
the internal pointer (cf. the description of the PGLOCK exit). 
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PGLOCK exit: 


This exit is meaningful only if this file was opened with SHARUPD=YES. A 
branch is made to the PGLOCK exit if the program tries to Lock a block that 


has already been Locked. 


If this exit is not used (default value or NO is specified) and the required 
block is Locked, the user waits until he can access this block. He is not 
informed of the "busy" status. 


Control is passed to the user at this exit whenever a data bLock has to be 
referenced during processing of an action macro and is inaccessibLe because 
of the manner in which another user is Locking it. (For exampLe, if user A 
has Locked a data block and user B also tries to Lock it, user B will be 
given control at the PGLOCK exit.) 


It is possible for any ISAM macro issued for a file opened with SHARUPD=YES 
to cause control to be passed to this exit. 

If this exit is taken, the “internal pointers" are in most cases invalid. 
Consequently it is necessary to reposition the pointers: the RETRY macro 
repeats the operation which caused the PGLOCK exit to be taken, or 
repositions the appropriate pointer (cf. the description of the RETRY macro). 
Macros for direct access can also be issued (e.g. GETKY, STORE, INSRT, SETL 
and ELIM (with KEY)). 


Notes on using shared update facilities 


- When to use ISAM shared update 


Specifying SHARUPD=YES for a file causes ISAM system tables to be set 
up in cLass-4 memory, while SHARUPD=NO causes the creation of at most 
tvo tabLe entries. 


If SHARUPD=YES is specified, these tables are updated with every ISAM 
macro. If SHARUPD=NO is specified, the entries are updated at OPEN/CLOSE 
time onLy. 


Thus, in order to save time and cLass-4 memory, SHARUPD=YES should be 
specified only when it is absolutely necessary for more than one user 
to open the file at the same time, and when at Least one of the users 
wishes to update it (e.g. OPEN-INOUT, OUTIN, EXTEND). 


- Opening and closing an ISAM shared update file 


When a file is opened with SHARUPD=YES, detailed tables are created in 
cLass-4 memory. These tabLes are checked and maintained by OPEN. 


In generat, to avoid unnecessary overhead, a user should not open a file 
until he is ready to process it, and he should not close it until 
processing is finished. 


CLOSE processing will unlock any data block the user has Locked in that 
file. 


U805-J-Z55-5-7600 6-45 


ISAM 


- Locking and unlocking data blocks 


Issuing macros which Lock or unlock data blocks can cause unnecessary 
overhead. 


In some situations, this overhead is unavoidabLe, as in the case of the 
GET/PUTX sequence, where SHARUPD=YES is specified and the GET macro has 
to Lock the data block and the PUTX macro has to unlock it. 


However, by dint of careful programming, the user can avoid such 
situations, which arise when GET macros are issued either with the LOCK 
specification for two or more files, or with the LOCK and UNLOCK 
specifications for the same file. 


- Use of records with the same key for shared update files 


If a user is reading a file sequentially (i.e. is using a GET, GETR or 
GETFL macro) and the file vas opened with SHARUPD=YES and DUPEKY=YES, 
he must be aware that the file may contain records with the same key. If 9 
user B has modified an index page associated with the data block user A 
wants to read, it may be necessary for ISAM to reposition the user in 
the file on the basis of the modified index pages. To do this, ISAM 
issues a SETL KEY to reposition the user. However, if the key involved 
is one of a sequence of duplicate keys, the user may be positioned to 
an undefined record in the sequence. Therefore, it is the user's 
responsibility to keep track of which record in the sequence he has 
processed. 


The RETRY macro may cause the same unexpected positioning for a file 
containing duplicate keys. This condition is described in detail under 
the section referring to the RETRY macro. 


6.3.6 General ISAM Programming Notes 


If a file was opened in the OPEN mode OUTPUT or OUTIN and then closed again, 

a null file is created. The number of the Last page (LASTPG) is then 

incremented by one, e.g. when BLKSIZE=(STD,6), LASTPG=7. 

If a null file is created by deleting all records using the ELIM macro, 2 
the Last page pointer is retained. 


ISAM does not prohibit opening of a null file if the OPEN mode is other 
than INPUT. If an empty file is opened in INPUT mode, control is passed to 
the user at the OPENER address of the EXLST macro. If, when processing a 
null file, an action macro contingent on the existence of data records is 
executed (e.g. GET), an EOF exit is taken. | 


When creating a file with BLKSIZE-(STD,n) where n is greater than 1, the 
user is required to allocate n*1 PAM pages with /FILE prior to opening the 
file. Failure to allocate sufficient space will result in an OPENER exit 
being taken. 


The processing time required to insert new records is reduced if the user 
can roughly estimate the extent of future file expansion. This estimate is 
specified via the PAD operand when creating the file. Although the ISAM 
routines attempt to optimize the splitting of data blocks when new records 
are entered in the file, such splitting requires a number of additional 1/0 
operations and should therefore be avoided. 
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When determining the PAD value for a file the following should be noted: 
Should the user select a PAD value which, added to the RECSIZE, exceeds the 
BLKSIZE, the DMS will prohibit file opening. Error code ODBC is used to 
indicate this error condition. 

If action macros are used, each of them operates with an internat pointer. 
Usually, this pointer is set to the record currently being processed by the 
action macro. The pointer is modified by the next action macro. It may 
reference an "imaginary" position. 


The ISAM pointer conventions are discussed at the end of this section. 


Hote for ISAM processing when using defauLt functions 
For example, if an FCB macro is specified as follows: 
FCB LINK=X,EXIT=Y,IOREG=9 


© the file will be an ISAM file with RECFORM=V and KEYPOS-5. 


These default values are assigned at assembLy time (macro ον, time). 
Therefore, if a user issues the following FILE command: 
/FILELA,LINK=X,RECFORM=F ,OPEN=OUTPUT 

the RECFORM will in fact be changed to "fixed", but KEYPOS will remain 5. 
A second example uses the same FCB and the command: 
/FILE.B,LINK=X,OPEN=OUTPUT 


Since IOREG is specified in the FCB macro, the ISAM macros specified for 
this file, when open, will operate in Locate mode. 


As no value is specified for RECSIZE, RECSIZE=BLKSIZE is assumed. As PAD is 
also not specified, 15% of the buffer size is reserved for padding. 


If the user now attempts to issue a PUT macro (in Locate mode) without 
changing RECSIZE, RECSIZE will be greater than the area available in the 
© buffer for the user's records, and the PUT macro will result in an error. 


Size of ISAM files 


Because of the many options which the user can exercise in the creation of 
an ISAM file, it is generally not easy for him to determine the size 

of the file, the number of index blocks or the number of index Levels. 

The following formulae facilitate the specification of certain vaLues, but 
they should not be regarded as anything more than rules of thumb. 
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e Data blocks: 


RDB=FLOOR (BS/RS) 
NDB=CEIL (NR/RDB) 


where: 

FLOOR = Greatest integer Less than 
CEIL = Smallest integer greater than 
RDB = Records per data block 

BS = Block size 

a) Block size = 2048 times the number of PAM blocks specified 
in the BLKSIZE operand. 

b) If the file was created sequentially by means of the PUT 
macro, BLKSIZE must be adjusted accordingly by being 
multiplied by (100-PAD)/100. 

Note: 2 
The default value for PAD is 15. 

c) If the file was created either sequentially or randomLy by 
means of the STORE or INSRT action macro, the file is 
densely packed. Therefore the value of BLKSIZE given in a) 
above should be used regardless of any PAD value. 

RS = Record size 
a) For fixed-Length records (RECFORM=F), add 4 to the value 
specified in RECSIZE. 
b) For variable-length records, use the average record Length. 
Note: 


As a result of support provided for new disk devices, there may be changes 
with respect to the processing of PAM pages. The area vithin PAM pages vhich 
can be used as the data area may be reduced as of the next version of the 


System. | 9 


e Index bLocks: 


NB *(KL+4) 


i-1 
NB = CEIL ( ) 
1 size 
where: 
NB = Number of bLocks at Level i. 
i 
NB = Number of blocks at Level i-1 (NB = NDB). 
1-1 ο 
κι. = Key/flag Length, i.e. the sum of: 


KEYLEN + LOGLEN + VALLEN 
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size = The effective size of the index block at Level i. 


a) If level i is the highest Level, size = 2012 bytes, 
otherwise size = 2044 bytes. 


b) If the file is created sequentially by the PUT, STORE 
or INSRT action macro, the size given in a) above must 
be adjusted by multiplying it by 0.5, except when i is 
the highest Level index. 


c) If the file is created completely randomly, the value 
given in a) above is only approximately accurate. 


d) If the file is created randomly by means of sequential 
PUT, STORE or INSRT macros, an adjustment factor between 
0.5 and 1.0 should be used. 


ExampLe: è b 


- Given: 


STD blocks, 1000 80-byte records, KEYLEN=8, LOGLEN-2, VALLEN=2, 
RECFORM=F, PAD=10. 


The file was created sequentially with PUT action macros. 
RDB = FLOOR (2044*0,9/(80*4))-221 
Each data block therefore contains 21 records. 
NDB = CEIL (1000/21) = 48 
There are 48 data bLocks in the file. 
48*(8*4) 

NB = CEIL ἰ------------- = 1 

i 2012 
Thus only one index block is required; the total number of halfpages in 
the file is 49. 
Given: 


STD bLocks, 100000 100-byte records (average), KEYLEN=5, 
LOGLEN=1, VALLEN=0, RECFORMsV. Ἢ 


The file was created sequentially with the STORE action macro. 
RDB = FLOOR (2044/100) = 20 
Each data block therefore contains approximately 20 records. 
NDB = CEIL (100000/20) = 5000 
There are approximately 5000 data blocks in the file. 
5000*(6+4) 
NB = CEIL (m) = 49 
1 2048/2 
Thus, there are 49 LeveL-1 index blocks in the file. 
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49*(6+4) 

NB = CEIL (——) = 1 

2 2012 
The highest Level index block in the file is therefore Level 2. It can 
be seen from the above calculation that the file would have to contain 
about 4 times the specified number of data records before index Level 
3 is required. The total number of halfpages required by the file would 
be: 


5000 + 49 + 1 = 5050 


Data block splitting 

If a new record does not fit where the index indicates it should, the data 
block is “split” in such a way that the two halves of the data block are 
moved from the original block into new, empty blocks. 

ExampLe: 


Splitting a data block. Assume the following file exists: 


Block 1 ~ Index block entry 1 


Key 7 


Block 2 


Block 2 = Data block 


Record with Record with Record with 
key 1 key 3 key 7 


Block 3 - Data block 


Record with Record with Record with 
key 10 key 15 key 20 


The user now specifies that a record with a key of 5 is to be inserted. 
Since no space remains in block 2, which is the Logical block that should 
contain the record, block 2 is split and the file now has the following 
structure: 


Block 1 - Index block 


Key 3 Key 7 Key 20 
Block 4 Block 5 Block 3 


Block 2 = Unused bLock 
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Block 3 - Data block 


Record with Record with Record with 
key 10 key 15 key 20 


Block 4 - Data block 


Record with Record with 
key 1 key 3 


Block 5 
Record with Record with 
key 5 key 7 
When splitting a data block two new PAM pages are used. The old page is 


Note: 
released for future use. 


6.3.7 ISAM Pointer Rules 


ISAM action macros (including OPEN) perform two main functions: 
1. Setting an internal pointer to a specific record. 


2. Executing the desired action for the record currently being referenced. 


6 Notes: 


- A pointer is updated before the action is performed. 
- Certain macros do not require the pointer to be updated. 


- With certain macros, only the pointer is updated and no other action is 
performed. 


The ISAM macros are summarized in the following table. 
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ISAM 
action 
macro 


ELIM 


GET 


GETFL 


GETKY 


Pointer 


If KEY is speci- 
fied, the pointer 
is moved to the 
first record vith 
the specified 
key. Otherwise 
the pointer is 
not moved. 


The pointer is 
moved forward 
one record. 


.The pointer is 


moved to the 
record retrieved. 
If no record is 
is retrieved, 

the file is 
positioned so 
that a subsequent 
GET (GETR) will 
either retrieve 
the record with a 
key greater than 
(Less than) or 
equal to the key 
within the 
defined Limits, 
or result in an 
EOF condition. 


The pointer is 
moved to the 
record with the 
specified key, or 
to the position 
in the file where 
such a record 
would exist, if 

a matching key 

is not found. 


Action 


ELiminates the 
record from the 
file. 


Retrieves the 
record referenced. 


Retrieves the next 


sequential record 
which satisfies 
the flag criteria. 


Retrieves the 


record referenced, 


if it exists. 


Comments 


ELIM can be regarded as 
a Leftshift operation of 
that portion of the file 
to the right of the 
defined record. Con- 
sequently, successful 
ELIMs need not update 
the pointer. 


1. If the pointer refers 
to a record outside the 
file, the user is given 
control at his EOFADDR 
address. 


2. If the previous macro 
was a SETL or ELIM for 
a record with a speci- 
fied pointer, the 
pointer is not moved 
before the record is 
retrieved. 


The record which would 
have been retrieved by a 
corresponding GET or GETR 
macro is the first record 
scanned for the flag 
criteria when a GETFL 
macro is issued. 


In terms of pointer theory 
one can consider a GETKY 
for a non-existent record 
to be equivalent to a 
GETKY for a record of 
Length O in between two 
existing records. Thus, a 
subsequent GET or GETR 
will work correctly (see 
GET, comment no. 1). 
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macro 


GETR 


INSRT 


OPEN 


PUT 


PUTX 


Action 


Pointer 


Retrieves the 
record referenced. 


The pointer is 
moved backward 
one record. 


Inserts the record 
at the Location 
pointed to. 


The pointer is 
moved to the 
position speci- 
fied by the 
record key. 


The pointer is 
positioned to an 
imaginary record 
immediately 
before the first 
record in the 
file. 


Places the record 
in the file at the 
referenced 
position. 


The pointer is 
moved just beyond 
the current end 
of the file, if 
it is not 
already there. 


Places the record 
in the file at the 
referenced 

position. 


The pointer is 
not moved. 
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Comments 


1. If the pointer points 
to a record situated 
before the beginning of 
the file, the user is 
given controL at his 
EOFADDR address. 


2. See GET, comment no. 2. 


The record is not inserted 
if a record already exists 
with the given key. How- 
ever, the pointer still 
points to the place in the 
file at which the record 
would have been inserted. 
This record can be 
described as a record of 
Length O. A GET macro 
following an unsuccessful 
INSRT macro retrieves the 
duplicate record. 


OPEN is decribed here only 
in relation to its effect 
on the pointer. The action 
caused by OPEN is 
described elsewhere. 


An additional check is 
made to ensure that a 
successful GET, GETR, 
GETFL or GETKY macro has 
been issued just prior to 
PUTX. Thus, the fact that 
the pointer is not updated 
cannot cause inadvertent 
errors. 
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ISAM 
action 
macro 


RETRY 


SETL 


STORE 


Table 6-6: 


Pointer Action 


Depends on the Performs the Last 
operation to be action macro, posi- 
repeated, or on tions the file for 
the positioning the user program 
operation. or places the 
program in a queue. 


The pointer is No action takes 
moved to: place. 


1. an imaginary 
record immediate- 
Ly before the 
first record in 
the file (if B 

is specified). 


2. an imaginary 
record immediate- 
Ly after the Last 
record in the 
file (if E is 
specified). 


3. the (first) 
record with the 
specified key or 
the place in the 
file where such 
a record would 
exist. 


The pointer is Stores the record 
moved to the at the desired 
position speci- Location. 

fied by the 

record key. 


Summary of ruLes for ISAM pointers in 


Comments 


RETRY itself does not 
affect the pointer except 
when it results in the 
execution of an action 
macro which does move the 
pointer. 


1. Using SETL effectively 
nuLLifies the pointer 
movement associated 
with a subsequent GET 
or GETR macro. 


2. For the purpose of 
cLarifying the pointer 
pLacement, a SETL macro 
(for a subsequent GET 
or GETR macro) for a 
non-existent record may 
be considered to be a 
SETL macro for a record 
of the Length 0, albeit 
at the correct 
position. 


This does not cancel 
updating of the pointer 
by the subsequent GET 
or GETR macro. 


If DUPEKY=YES: 

If a record vith the given 
key already exists in the 
file, the pointer is set 
to the position immediate- 
Ly following the duplicate 
record. The record is 

then stored. 


action macros 
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6.3.8 Use of PAM Keys in ISAM 


The rightmost eight bytes of the PAM key in ISAM files are: 


LLPPUUFF 


where: 

LL is the page Length (i.e. the highest byte position used in the page). 

PP is a pointer to the first Logical record in a data block. If this is an 
index page, the value is 0; it will also always be O for data pages as 
of Version 7.1. 


UU contains the Location of the Last record to be used. 


FF is a pointer to the first block of free space in the page. If there is 
e no free space, FF points to the end of the bLock. 


ISAM records within a data block are chained; record i points to record i*1; 
the Last record points to record 1. Ur 
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6.3.9 ISAM Macros 


FCB CREATE FILE CONTROL BLOCK «TYPE 0» 


The following format indicates the operands which may be used in the FCB 
macro in conjunction with ISAM. These operands are described in detail in 
section 5.4, "Service Macros for Disk Fives". 


Operation 


FCB 
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Operands 


FCBTYPE=ISAM 


(reLexp) 
C,BLKSIZE= J 


þ C,DUPEKY=YES]J texte] 
reLexp 


(STD,absexp) 


[,FILE=filename] [,FORM=SHORT] 


 [,IOREG-regno] 


L,KEYARG-reLexp L,KEYLENzabsexplL ,KEYPOS-zabsexp1l]l 


INPUT 
OUTPUT 


C,LINK=Linkname] Γ,ΟΡΕΝΞΙΕΧΤΕΝΟΙ1 C,OVERLAP=YES] [,PAD=absexp] 
INOUT 
OUTIN 


lj 


L,PASS-passvord] (C,RECFORM= ] 


C,RECSIZE=absexp] L,RETPD-zdaysl 


YES 
t/SHARUPD=| ha C,LOGLEN=absexp][,VALLEN=absexp] 
NO | 
MAX NO YES 
C , VALPROPz 1 L,WROUT- 1 L,WRCHK-z J 
MIN YES NO 
code 
C,OPTION= J 
(code,code) 
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Note: 


Table 5-2 in section 5.4.4 summarizes the operands which may be specified. 
DUPEKY=NO is applicable only if neither FCB nor FILE contains the operand 
DUPEKY=YES. 


If OPEN=INPUT, INOUT or EXTEND, KEYLEN is always overwritten with the infor- 
mation contained in the ISAM Label. 
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ELIM ISAM 


ISAN ACTION MACROS 


ELIM ELIMINATE RECORD «TYPE R> 


The ELIM macro eliminates records from a file. 
Operation Operands 

fcbaddr KEY 
ELIM Ls 1 

(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


KEY The key of the record to be eliminated is Located at the 
address defined by KEYARG in the FCB. 


(0) - The address in register O is different from that in the 
FCB. Here it refers to the record to be eliminated. 


- The address in register O is the same as that in the 
FCB. Here the Last record previously retrieved by a GET, 
GETFL, GETKY or GETR macro is eliminated. 

The Latter is also the default value if the operand 
CKEY/(0)] is not specified. 


Programming notes: 


- No other ISAM action macro can be executed between the associated GET, 
GETR or GETKY macro and the action macro ELIM (without KEY). 


- If the KEY operand is specified and a record with the specified key 
cannot be found, control is returned to the user at the NOFIND exit 
(see the EXLST macro). 


- If duplicate keys exist in the file and if the KEY operand is specified, 
the record first placed in the file is eliminated. 


- Although the ELIM macro (without KEY) must normally be preceded by a GET, 


GETR, GETFL or GETKY macro, it may be executed for the first record in 
the file if it follows an OPEN macro in INOUT mode. 
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GET GET RECORD «TYPE Ro 


The GET macro retrieves the next sequential record of a fiLe. 


Operation Operands 


fcbaddr area LOCK 
GET ty af, ] 
(1) (0) NOLOCK 
fcbaddr | This operand specifies the address of the FCB associated 


with the file to be processed (exit address). 
(1) The FCB address is Located in register 1. 


area This operand specifies the address of the area into which 
the record is moved (exit address). 


(0) The address of the area into which the record is to be 
moved is Located in register 0. 


LOCK This operand indicates that the data bLock containing this 
record is to be Locked once the record has been retrieved. 


NOLOCK This operand indicates that the data block containing this 
record is not to be Locked following execution of this macro. 


Programming notes: 


- The "area" operand is ignored if the IOREG operand vas specified in the 
FCB. 


- If a record beyond the end of the file is requested, the user is given 
control via EOFADDR (see the EXLST macro). | 


- If the file contains records with duplicate keys, they will be retrieved 
on a "first in, first out" (FIFO) basis. 
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GETFL GET RECORD BY FLAG «TYPE 5» 


The GETFL macro is used to retrieve the next record (in forvard or reverse 
direction) vithin the specified range. 
Its fLag must satisfy the conditions specified by the macro. 


Operation Operands 


GETFL P| ne ος | 
C, It, 1 
(1) (0) NOLOCK 


KEY ANY 
] L,LOGTEST- 


h [,MF-L] L,REVERSE-YES] 
END. 


tare] 
ALL 


L,VALTEST- J 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


area This operand specifies the address of the area into which 
the record is to be moved (exit address). 


(0) The address of the area into which the record is to be 
moved is in register O. 


LOCK The data bLock containing this record is to be Locked 
before the record is read. 


NOLOCK The data bLock containing this record is not to be Locked 
following execution of this macro. 


LIMIT= The file scan for the next record starts from the current 
position in the file. The positioning may be the result of 

a SETL or GETKY macro, for instance. 

=KEY The scan continues until: 

a) the Last record which (in forward scan) has a key Less 
than the key contained in the key field of the area 
referenced by KEYARG. 

b) the Last record which (in reverse scan) has a key 
greater than the key contained in the key field of the 
area referenced by KEYARG. 


= The scan continues until the end of the file is reached. 
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LOGTEST=ANY If this operand is specified, only those records are 
retrieved whose Logical flag matches at Least one of the 
bits of the mask stored in the Logical flag portion of the 
area referenced by KEYARG. 


=ALL A record is retrieved if its LOG field bit configuration 
coincides with the bit configuration in the mask, although 
additional bits may be set in the record LOG fieLd. 
MF= This operand specifies the type of macro expansion. If no 
entry is made, type R is assumed. 


If L is specified, the following two-word operand List is 
generated: 


Operand byte 1 FCB address or register number 
(1 byte) (3 bytes) — 

Operand byte 2 Area address or register number 
(1 byte) (3 bytes) 


The meaning of the fields in the operand List is as 
follows: 


Operand byte 1 
- Coded GETFL operands (see Table 6-7a). 
FCB address/register 


- Either the FCB address or a register (right-justified) 
containing the address of the FCB. 


Operand byte 2 
© = Coded GETFL operands (see Table 6-7b). 
Area address/register 
- The address of the area to which the record is to be 


moved, or a register (right-justified) containing the 
address of that area. 
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Bit position Meaning (VALTEST=) 


ΤΠ 
πας 
ZESERERES 
SERERETE 
OEE: 
SESE 
0 | o|oj|o null or invalid 
3 1 LOGTEST operand specified » 
ο LOGTEST null or invalid 
2 1 LOGTEST=ALL 
ο LOGTEST=ANY 
1 1 LIMIT=KEY 
O LIMIT-END, null or invalid 
ο 1 REVERSE=YES 
ο REVERSE=null or invalid 


Table 6-78: GETFL operand bit configuration - byte 1 


Bit position| Meaning 


7 1 LOCK specified (or default valuo) 
Ὁ NOLOCK specified 
6 1 FCB address in register 2 
ο FCB address specified 
5 1 Area not specified 
O Area specified 
4 1 Area address in register 
O Area address specified 
3-0 not used 


Table 6-70: GETFL operand bit configuration - byte 2 
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- ISAM GETFL 


A GETFL macro which is to use operands contained in a 
Separate operand List has the following format: 


Operation Operands 


List 
GETFL MF=(E, ) 
(1) 


If this format is used, the code is generated to Load 
registers 0 and 1 (based on the contents of the operand 
List), and the GETFL SVC is then issued. 


The "List" operand specifies the Location of the operand 
List to be used for this action (exit address). If the 
operand List shows that the FCB and area addresses are 
e contained in registers, these registers must be Loaded 
before the macro is executed. 

Programming notes: 


- The "area" operand is ignored if the IOREG operand was 
specified in the FCB (assuming Locate mode). 


- If a record whose flag is within the specified Limits is 
not found, control is passed to the NOFIND exit (see the 
EXLST macro). 


- If the file is positioned to a record containing the 
LIMIT key specified in a GETFL action macro, the NOFIND 
exit is taken and the file position is Left unchanged. 


- If LIMIT-END is specified or taken as the default value, 
file scanning proceeds to the end of the file if pro- 
cessing is in forward mode, or to the beginning of the 
file if in reverse mode. If file search conditions are 
not satisfied, the EOF exit is taken. 


- If VALTEST and LOGTEST are both specified, both con- 
(< ditions must be met for the record to be retrieved. 


- If neither VALTEST nor LOGTEST is specified, all the 
records are searched until the Limit is reached. If a 
KEY Limit was specified, the NOFIND exit is taken; if 
LIMIT=END is specified, the EOF exit is taken. 


- If the KEYARG of a GETFL macro references a Logic mask 
containing onLy binary zeros, the user error exit is 
taken. If LIMIT-KEY is specified, the file is processed 
in forvard/reverse direction and the key portion of the 
area referenced by KEYARG is Less/greater than the key 
of the record at which the file is currently positioned, 
control is transferred to the USERERR address via the 
EXLST macro. 
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- Any attempt to apply the GETFL macro to a file created 
without flags, and any attempt to output a record to a 
flagged file which is not Large enough to accommodate a 
full index (key, value flag, and Logical flag) wilt 
result in control passing to the USERERR address. For 
flagged files, KEYARG must point to a user-defined field 
Large enough to accommodate the entire index (KEY, value 
flag and Logical flag). 


REVERSE=YES The scan takes place in reverse order (toward the 
beginning of the file). 


VALTEST= Only those records are retrieved whose value flag is 
related as required to the information stored in the value 
flag portion of the area referenced by KEYARG. 


Meaning of the relationship symbols: 


-GT greater than 2 
-GE greater than or equal to 

-EQ equaL to 

=NE not equal to 

=LE Less than or equal to 

=LT Less than 
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GETKY GET RECORD WITH SPECIFIED KEY «TYPE Ro 


The GETKY macro retrieves, in random access, a record with the specified 
key. Prior to execution of the macro, the record key must be stored at the 
address specified in the KEYARG operand of the FCB. 


Operation Operands 


fcbaddr area LOCK 
GETKY Ly Jt ] 
(1) (0) NOLOCK 
fcbaddr This operand specifies the address of the FCB associated 6 
with the file to be processed (exit address). 
- (1) The FCB address is Located in register 1. 
area This operand specifies the address of the area into vhich 


the record is to be moved (exit address). 


(0) The address of the area into which the record is to be 
moved is in register O. 


LOCK The PAM bLock containing the record vith the specified key 
is to be Locked once the record has been retrieved. 


NOLOCK The PAM block containing the record with the specified key 
is not to be Locked once the record has been retrieved. 


DefauLt value: Move mode, i.e. the record is transferred to the address 
"area". 


Locate mode: This macro places the address of the record in the register 
specified by the IOREG operand. 


© Programming notes: 


- The "area" operand is ignored if the IOREG operand was specified in the 
FCB. 


- If a record with the specified key is not found within the file, the user 
is given control at the NOFIND address (see the EXLST macro). 


- After GETKY is issued, the position indicators for GET and GETR are set 
as if a GET macro had been issued to retrieve a record. If the GETKY 
macro was not successful, a subsequent GET or GETR macro is used to 
retrieve a key greater or Less, respectively, than that of the record 
GETKY failed to retrieve. If a file contains records with duplicate keys, 
the GETKY macro retrieves the first of these records. 
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GETR GET RECORD REVERSE «TYPE R> 


The GETR macro retrieves the next record in the file in reverse order (i.e. 
tovard the beginning of the five). 


Operation Operands 


fcbaddr area LOCK 
GETR a a pe a ] 
(1) (0) NOLOCK 
fcbaddr | This operand specifies the address of the FCB associated 


with the file to be processed (exit address). 
(1) ‘The FCB address is Located in register 1. 


area This operand specifies the address of the area into which 
the record is to be moved (exit address). 


(0) The address of the area into which the record is to be 
moved is in register 0. 


LOCK The data bLock containing this record is to be Locked once 
| the record has been retrieved. 


NOLOCK The data bLock containing this record is not to be Locked 
following execution of this macro. 


Programming notes: 


- The "area" operand is ignored if the IOREG operand vas specified in the 
FCB. 


- If a record outside the file is requested, the user is given control via 
EOFADDR (see the EXLST macro). The program can switch from GET to GETR 
and vice versa at any time, without the file having first to be 
repositioned to the end or the beginning of the file, as the case may be. 


- If a GET macro supplies a record with the key K , and the subsequent 
n 
macro is a GETR, then the next record to be retrieved is the one with 
the key K , Subject, however, to the following formula: 


- If the file contains records with duplicate keys, the duplicates are 
retrieved on a "Last in, first out" basis if the GETR macro is issued. 


- If the file vas positioned to an existing record using SETL KEY, a 
subsequent GETR macro retrieves this record. 
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INSRT INSERT RECORD «TYPE R> 


The INSRT macro transfers a Logical record from the user's area to the 
file (in the position determined by the value of its record key). 


Operation Operands 
fcbaddr area 
INSRT ΄ 
(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


area This operand specifies the address of the Logical record 
to be inserted in the file (exit address). 


(0) The address of the record to be inserted in the file is in 
register Q. 


Programming note: 


If the file already contains a record with the specified key, the new record 
is not transferred (irrespective of whether DUPEKY=YES was defined in the 
FCB). Control is passed to the user via DUPEKY (see the EXLST macro). 

The record must be retrieved in the area determined by the "area" operand 
even if IOREG vas specified in the FCB. 
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ISREQ UNLOCK DATA BLOCK «TYPE 0». 


The ISREQ macro is used to unlock a data block in an ISAM SHARUPD file. A 
data bLock remains Locked if it has been read, but not updated and 
rewritten, i.e if no further action macro is issued after the read macro. 


Operation Operands 


ISREQ fcbaddr 
zACTLON=UNLOCK 
(r) 


fcbaddr This operand specifies the address of the FCB associated 
with the file in which a data block is Locked. 


(r) The FCB address is Located in register "r". 


ACTION-UNLOCK This operand specifies the action to be performed. Both 
operands must be specified to effect unLocking. 


Note: 


The ISRE@ operand UNLOCK need not be used if a further action macro is to be 
issued for a SHARUPD file. A data block is then unLocked implicitly by ISAM 
before the action macro is executed. After unLocking by means of ISREQ, ISAM 
always returns to the next macro. The IDIECB field contains one of the 
following error codes, which affect register 1 as follows: 


Meaning: 


not changed Data bLock unlocked 


changed Data block Locked in another 
file 


not changed No data block to unlock 


not changed FCB or address invalid 


In the case of error code ΑΟΙ, register 1 specifies the address of the FCB 
associated with the file in which the data block is Locked. To unlock it, 
the user need only issue the ISREQ macro with the UNLOCK entry, specifying 
"register 1" as the first operand. 


ExampLe: 


In RFA mode the data block has already been unlocked when AO1 is specified, 
Leaving register 1 unchanged. 


ISREQ FCBA,ACTION-UNLOCK 
CLC ID1ECB,=X" A01" 

BNE NAME 

ISREQ (1) ,ACTION=UNLOCK 
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OSTAT OBTAIN INFORMATION ON OPENED FILES «TYPE Ro 


The OSTAT macro provides the user with information about the users who have 
opened a given file. The following information is supplied: 


a) the number of users who have opened the file; 


b) the number of users who have opened the file as an ISAM file with all 
the possible OPEN/SHARUPD combinations; 


c) the number of users who have opened the file with some other access 
method for the purpose of input or updating. 


Operation Operands b 


© fcbaddr area 
OSTAT La ] 


(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file for which the OPEN mode information is to be 
obtained (exit address). 


(1) The FCB address is Located in register 1. 


area This operand specifies the area into which the information 
is to be moved (exit address). 


(0) The address of the area into vhich the information is to be 
moved is in register O. 
Programming notes: 
- Once the macro has been processed, register 1 will contain the address of 
the FCB and register O will contain the address of the area to which the 
6 . information vas moved. The Low-order bytes of register 15 wilt contain 


zero or an error code. 


The user must have opened the file before issuing the OSTAT macro. The 
user's OPEN/SHARUPD combination is also included in the information. 


- The area into which the information is moved is defined by the dummy 


section (DSECT) IDOST, a description of which can be obtained by the 
IDOST macro expansion. 
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PUT WRITE RECORD «TYPE R> 


The PUT macro presents a Logical record to the system to be included in the 
output five. 


Operation Operands 
fcbaddr area 
PUT É, ] 
(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


'" area This operand specifies the current address of the Logical 
record to be written to the output buffer (exit address). 


(0) The address of the record to be written to the output 
buffer is in register O. 


Programming notes: 


- The "area" operand is ignored if the IOREG operand (i.e. Locate mode) vas 
specified in the FCB. 


- The PUT action macro should be used only to add records to the end of an 
existing file. If a file is opened in INOUT or OUTIN mode and the Last 
macro for the file vas not a PUT, PUT causes a SETL macro to be performed 
at the end of the file before the record is written to that file. 

Issuing a PUT macro in Locate mode has the following results: 


a) The record previously generated in the buffer is checked and added 
to the file. 


b) The address at which the next record is to be generated is placed in 
IOREG. | 


Since a valid IOREG value must be supplied before a record can be 
generated, a dummy PUT macro is issued before creating the first 

record in the file. Similarly, a valid record must be generated after the 
Last PUT macro prior to closing the file. Otherwise a CLOSE error exit 
will be taken or a corrupted record will be appended to the file. 


= In the case of format-V records, the value of the FCB field ID1RECSI must 
equal or exceed the size of the records added to the file. 
This can be achieved by specifying, in the RECSIZE operand of the FCB, a 
value equal to or greater than the maximum size of all records to be 
created. If RECSIZE is not defined, the value of BLKSIZE is used. 
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- This macro ensures that the key of any record added to the file is equal 
to or greater than the current highest key value. If the strict key 
sequence is broken, the user receives control at one of the following 
exits (see also the EXLST macro): 


- at the DUPEKY exit if the key of the current record is equal to the 
key of the preceding record and DUPEKY=YES is not specified. 


- at the SEQCHK exit, if the key of the current record is Less than 
the highest key of the existing file. 


- In the case of simultaneous updating, the Last Logical block in the file 


remains Locked by a task until another action macro (apart from PUT) is 
called by this task. 
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PUTX REPLACE RECORD «TYPE R> 


The PUTX macro replaces Logical records of a file. The record to be replaced 
must first be retrieved by a GET, GETR, GETFL or GETKY macro. 


Operation Operands 
PUTX fcbaddr area 
Wr 1 
(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


area This operand specifies the address of the Logical record to 
be written to the output buffer (exit address). 


(0) | The address of the record to be written to the output 
buffer is in register O. 


Notes: 


- In Locate mode, a PUTX macro does not cause the buffer to be rewritten. 
An identifier indicating that the buffer has been changed is simply added. 
Output does not occur until the next macro is issued, as soon as an SVC 
(e.g. GETKY, GET, GETR) is issued vithin the same FCB. 


- The record key cannot be changed during the update process. If the key is 
changed in move mode, the user receives control at the SEQCHK exit (see 
the EXLST macro). 

If, during an update process in Locate mode, the record key is changed or 
the program inadvertently modifies other portions of the data buffer, the 
results of subsequent processing will be unpredictable. If the data 
buffer is altered so that it can no Longer be processed by ISAM, the user 
is given control at the USERERR exit (see the EXLST macro). 


- The Length of format-V records can be modified by the user only if he is 
operating in move mode. No other ISAM action macro can be issued for the 
file between the PUTX macro and the associated preceding GET, GETKY, 
GETFL or GETR macro. 


- If a PUTX macro is issued in move mode for a record vithin a series of 
records having duplicate keys, the position of the record vithin the 
sequence can be altered if the modification involves increasing the 
original record size. 
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RETRY X REPOSITION IN A FILE «TYPE 0» 


If the PGLOCK exit of the EXLST macro is activated, the internal pointers 
are not correctly positioned unless the macro which Led to this exit was a 
PUTX or ELIM (without KEY). Certain ISAM macros (GET, GETR, GETFL) will have 
updated the pointer before they branch to PGLOCK. The RETRY macro performs 
repositioning and can optionally reactivate the macro which Led to the 
PGLOCK exit. | 


Operation Operands 


POS 
RETRY FAILeexit-adurt,ACTiON- | RETRY [IC ,COUNT=integer! 
WAIT 


- FAIL=exit-addr This operand specifies the address which is to be given 
control if RETRY fails or it takes 30 minutes or more to 
access a bLock. 


ACTION= This operand specifies the action to be taken by RETRY. 
=POS The pointer is to be repositioned in the file. 
=RETRY The pointer is to be repositioned in the file and the ISAM 


macro repeated. 


=WALT If the operation is repeated and the block is still not 
available, the ISAM macro is queued. The program is not 
activated until the block required for this program is 
available. If the task waits 30 minutes to access the data 
block, control is given to the exit routine defined by FAIL. 


COUNT= Decimal number between O and 255. 
This operand specifies how often the repositioning/macro 
repetition is to be retried before control is transferred 
to the address defined by FAIL. 


© Default value: 1 


Notes: 


- This macro can be used only with the PGLOCK exit. If it is used elsewhere, 
a USERERR exit is taken, and IDIRTNAD in the FCB is Left pointing to the 
Last instruction in the RETRY macro expansion (unconditional branch 
to the FAIL address). 


- If ACTION-POS is specified and positioning is successful, control is 
_ returned to the job at the statement following the RETRY macro. 
If ACTION=RETRY is specified and the positioning/macro repetition is 
successful, control is returned to the job at the statement following 
the ISAM macro which was reissued. 
If either action fails (even after being retried the number of times 
specified by.COUNT), control is passed to the job at the Location 
specified by the FAIL operand. 
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- With the PGLOCK exit the job may use any register except register 1. If 
control is returned to the job as a result of RETRY, the job's 
registers have the same contents as they would have had if the action 
macro had been successful immediately. 


- If the Last record successfully accessed prior to the PGLOCK exit is one 


of a series of records with the same key, repositioning will position 
the task to the first record in this series. 
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SEIL POSITION FILE «TYPE R> 


The SETL macro enables positioning to take place to the beginning or end of 
a file or to any record determined by a specified key. 


Operation Operands 


SETL B 

fcbaddr E 

7) KEY 
(1) 
(0) 
fcbaddr This operand specifies the address of the FCB associated 
& with the file to be processed (exit address). 
(1) The FCB address is Located in register 1. 
B Positioning is to take place to the beginning of the file. 
E Positioning is to take place to the end of the file. 
KEY Positioning is to take place to the key defined by the 
KEYARG operand of the FCB. 

(0) Prior to the execution of SETL, the position code must be 


placed in register 0 as follows: 

B Ό 

E 4. 

KEY Address of the KEYARG field in the FCB 


DefauLt value: B 


e Programming notes: 


- If the KEY option is used and the specified key does not exist, 
positioning to the record vith the next higher or Lower key still occurs, 
without resulting in an error; i.e. the next GET macro reads the next 
higher record, and the next GETR macro reads the next Louer record. 


- If the KEY option is used and the specified key exists, both the GET 
macro and the GETR macro read the associated record. 


- If records with duplicate keys exist in a file, the position indicators 
are set so that the next GET macro fetches the record vhich vas the first 
duplicate record written to that file. 


- Performing SETL B for a null file causes control to be transferred to the 
EOFADDR error exit of the EXLST macro. 


UB05-J-255-5-7600 6-75 


STORE ISAM 


STORE STORE RECORD «TYPE R> 


The STORE macro obtains a Logical record from the user area and places it 
in the file at the position defined by the key. 


Operation Operands 
fcbaddr area 
STORE , 
(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


area This operand specifies the address of the Logical record 
to be stored in the file (exit address). 


(0) The address of the record to be stored in the file is in 
register O. 

Programming notes: 

- STORE has the same function as the INSRT macro. If, however, a record . 
with the same record key is found in the file, the new record overwrites 
the existing one. No DUPEKY exit is taken. 

- If DUPEKY=YES is specified in the FCB, duplicate keys are allowed. The 
new record is then placed in the file immediately after any other record 
with the same key. 


- The record to be stored must be retrieved in "area" even if the five is 
processed in Locate mode (IOREG). 
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9-4 SAM «SEQUENTIAL ACCESS METHOD» 


SAM provides a means of accessing records sequentially, beginning at 8 
specified point. This organization is most useful for making a search 
through all the records of a file, including retrieving and updating a 
specific record and returning it to the file. Records can also be added to 
the file. Unlike ISAM, no additional space is required other than that 
needed by the Logical records themselves. 


SAM automatically performs all blocking, debLocking and buffering for the 
user. If the user requests the system to utilize only one 1/0 area, then no 
buffering (overlapping) takes place. 


Logical records are retrieved by means of the GET macro. SAM expects records 
to be required in the same sequential order in which they were written. 
Logical records designated for output are output by means of the PUT macro. 
The program can continue as if writing of the data record would follow 
immediately, although the access method's routines may perform blocking with 
other Logical records and delay the actual writing until the output buffer 
has been filled. Buffers are automatically maintained by the system. SAM is 
Largely device-independent and allows files to be processed on disks and 
tapes. : 


Transfer of data to and from the file can be effected in either of two 
modes: 


Move mode: The user specifies the address of the record in his 
program, and the system is responsible for 
transferring it to or from the buffers. 


Locate mode: The user requests the address of the current record 
in the buffer area via a register. 
The user is responsible for transferring data to or 
from the buffers. In Locate mode, direct access to a 
record is possible via the retrieval address in the 
FCB (see section 6.4.3). 


The following action macros are available in SAM to control file processing: 


GET Retrieves the next record from the file in physically sequential 
order. 

PUT Writes a Logical record to the file. 

PUTX Returns an updated Logical record to the file (direct access only). 

RELSE Causes any remaining Logical records in a buffer to be bypassed for 


input. On output, the next Logical record created is written as the 
first record of a new buffer. 

SETL Specifies the position at which subsequent file processing is to 
start. 


For files opened in OUTPUT or EXTEND mode, SAM interprets each PUT or SETL 
macro as an end-of-fiLe indicator. The Last PUT or SETL macro prior to CLOSE 
for a file thus automatically defines an end-of-file indicator for the 
system. If the user wishes to delete all of the records beyond a given 
record, he can use the SETL macro to position to the desired point in the 
file, and then issue a CLOSE macro to close that file. 
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For direct access, a retrieval address is made available to the user. The 
format of this retrieval address is described in detail in section 6.4.3, 
“FCB Retrieval Address". When a Logical record is stored (by means of a PUT 
macro), its retrieval address is made available in the FCB. The user can, if 
he wishes, create another file from this retrieval address data and thereby 
establish a basis for subsequent non-sequential processing of the file 

being created. This retrieval address is also available in the FCB after 

the execution of a GET macro. Thus, even if the user did not create the 
file, he can still create a secondary file from the retrieval addresses to 
facilitate subsequent non-sequential processing of the original file. 


6.4.1 SAM Record Formats 


SAM supports three record formats, as follows: 
F (for fixed-Length records) 

V (for variabLe-Length records) 

U (for records of undefined Length) 


See section 6.1.3 for the format of Logical records. 


Note: 

For format-U records, SAM uses one Logical record per physical bLock 
(buffer). For example, a user who specifies standard bLocks (2048 bytes) and 
outputs 48-byte Logical records would vaste 2000 bytes. 


The size of the Logical record must not exceed the buffer size (see the 
BLKSIZE operand). 


6.4.2 Opening a SAM File 
The file can be opened in the following modes: 


INPUT Retrieve records from an existing file in the direction of the 
end of the file. 


OUTPUT Create a new file or replace an existing file. 

EXTEND Add records to the end of an existing file. 

UPDATE Retrieve and replace records in an existing file (Locate mode 
only). 


The PUTX macro is used to rewrite Logical records. Each record, 
however, must first be retrieved by a GET macro in Locate mode. 
The user must not change the Length of these records. 


REVERSE Retrieve records from an existing file in a reverse direction. 
MuLtivoLume files cannot be opened in REVERSE mode. 
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OPEN mode INPUT OUTPUT EXTEND UPDATE REVERSE 
X X X 
X X 
X X X 
X X X 
Table 6-8: SAM action macros in relation to OPEN mode 
Programming notes: b 


- - If a SAM file is created or replaced (OPENZOUTPUT), both the primary and 
= the secondary allocation must be a multiple of the block size. 


- In the case of OUTPUT and move mode operation vith 


- variabLe-Length records (format V) or 
- fixed-Length records (format F) and more than 1 record per block 


the primary aLLocation must be at Least twice the block size. If these 
requirements are not met, control passes to the EXLST error exit 
NOSPACE (insufficient memory space). 

- With OUTPUT and Locate mode, the user receives in IOREG the Location at 
which the first record starts, as soon as OPEN has been performed. If the 


first PUT macro has been performed, the user receives from IOREG the 
start of the second record etc. 


$.6.3 FCB Retrieval Address 

The P1FCB field ID1RPTR (one word) contains the retrieval address in the 
form bbbbbbrr, where: 

bbbbbb Number of the buffer in the file. 


rr Number of the Logical record within the buffer. The first record in 
the file has a retrieval address of 00000101. 


INPUT, UPDATE bbbbbbO1 


© Table 6-9: Retrieval address values after OPEN, SETL B and SETL E 
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"bb 
^ 
-ν 


"un 
foL 


The 
add 


GET 


PUT 


REL 


Not 


bbbb" stands for: 
ith EXTEND: the highest buffer number +1 in the file. 
ith INPUT/UPDATE: the highest buffer number in the file. 


changed" means that IDAIRPTR is not updated until after the GET macro 
Loving the SETL macro. 


other action macros have the following effect as regards the retrieval 
ress: 


If the specified record makes it necessary to retrieve a new 
buffer, bbbbbb identifies the buffer number for the record and 
rr is reset to 00. 


If the specified record makes it necessary to write the buffer, 
bbbbbb identifies the buffer number for this record and rr is 
reset to O0. In other words, the value is set to the number of the 
buffer in which the record is to be placed. 


SE If the file is opened in OUTPUT or EXTEND mode, bbbbbb is set to 
the number of the buffer in which the next record will be placed; 
rr is set to 00. 


This field is maintained only for tape files created with standard 
bLocks. : 


bbbbbb is buffer-oriented. 
Given: 


BLKSIZE=(STD,2) 
RECFORM=F 
RECSIZE=512 


The retrieval address for the 10th record is 00000202. The retrieval 
address for the 20th record is 00000304. 


The system never increments the rr field. As described above, it is reset 
to zero when a new buffer is to be processed. The user can increment the 
rr field if he wishes to maintain retrieval address information for each 
Logical record (IDFCB field ID1RPTR). 
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6.4.4 Use of PAM Keys in SAM 


The format of the rightmost eight bytes of the PAM key in SAM files is 
BBBXLLXX. 


where: 

BBB Buffer number in binary 

X Not used 

LL Length of useful data in the buffer 


The first X-byte (byte 4) is reserved for future system use. 


Note: 
A modification will be made in. respect to the support of preformatted b 


© disks (FBA disks), for which reason a user program cannot entirely count on 
obtaining information in exactly the form described above. 
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6.4.5 SAM Macros 


FCB © CREATE FILE CONTROL BLOCK «TYPE 0) 


The following operands may be supplied in the FCB for SAM. A detailed 
description of these operands can be found in section 5.4, “Service Macros 
for Disk Files". 


Operation Operands 


FCB FCBTYPE=SAM 
S (relexp) 
C,BLKSIZE= ] C,EXIT= ] C,FILE=filename] 
(STD,absexp) reLexp i 
NO 
[L,FORM-SHORTJ] L,IOAREA2- ] 
relexp 
INPUT 
OUTPUT 
C,IOREG=regno] [,LINK=Linkname] [,OPEN={EXTEND | 
REVERSE 
UPDATE 


F 
x 
passvord U 


} C,RECFORM= 1 L,RECSIZE-absexpl 
a A | 
eh. 
U N 


YES 
[,RETPD-days] [,VARBLD=regno] turche] h 


NO 

code 

C,OPTION= 1 
(code,code) 


teass-| 
absexp 


See chapter 5 for a description of the operands. 
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GET GET RECORD «TYPE i» 


The GET macro retrieves the next sequential record of a file. 


Operation Operands 


fcbaddr area 
GET E 1 
(1) (0) 
fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 
(1) The FCB address is Located in register 1. b 
- area This operand specifies the address of the area into which 


the record is to be moved if processing is in move mode 
(exit address). 


(0) The address of the area into which the record is to be 
moved is Located in register 0. 


Programming notes: 


- The "area" operand is ignored if the IOREG operand vas specified in the 
FCB. 


- If a record beyond the end of the file is requested, the user is given 
control at EOFADDR (see the EXLST macro). 


- The "area" operand is ignored for files opened in UPDATE mode. 


- In the case of SAM files, the access time can be minimized by using Large 
buffer areas. SAM itself then chains together consecutive PAM blocks 
(chained I/O). 

© However, worthwhile savings can be expected only in the case of files 
which have a substantial proportion of contiguous storage space (see the 
SPACE operand in the FILE command). 


Note: 
‘A\modification wi be made in/respect to/the support/af preformatted 


disks (FBA Wisksy, fori which feasen a usgr program cann&t entirely gunt or 
obtaining information in exactly the form describeg/abové | 
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PUT WRITE RECORD «TYPE Rò 


The PUT macro presents a Logical record to the system for inclusion in an 
output file. 


Operation Operands 
fcbaddr area 
PUT | de J 
(1) (0) 


fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


area This operand specifies the address of the Logical record to 
be written to the vue buffer (exit address). 


(0) The address of the record to be vritten to the output 
buffer is in register O. 


Programming notes: 


- The "area" operand is ignored if the IOREG operand vas specified in the 
FCB. 


- If this macro is issued in Locate mode, the system places the address of 
the first available area within the output buffer in the register 
specified in IOREG. The user must then ensure that the record to be 
included in the output file is made available at that address. 


- If format-V records are processed in Locate mode, the system places, in 
the register specified by the VARBLD operand, the buffer capacity 
remaining after every PUT. It is the user program's responsibility to 
ensure that the next record can be compLeteLy accommodated in the 
remaining buffer area. If it cannot, a RELSE macro must be issued. 


Note: 
A modification will be made in respect to the support of preformatted 


. disks (FBA disks), for which reason a user program cannot entirely count on 
obtaining information in exactly the form described above. 
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PUTX REPLACE RECORD «TYPE Ro 


The PUTX macro is used to return an updated Logical record to a file. The 
user must not change the Length of the record during the replacement 


process. 


Operation Operands 


fcbaddr 
PUTX 


(1) 


fcbaddr This operand specifies the address of the FCB associated b 
with the file to be processed (exit address). 


© (1) The FCB address is Located in register 1. 


Programming notes: 


- The PUTX macro can return only a record previously supplied by a GET 
macro in Locate mode. The file must be opened in UPDATE mode. 


- A macro does not Lead to an SVC in every instance. An SVC is onLy 
issued by the buffer management routine when a buffer is to be 
output. If the macro STIXIT SVC-... or STIXIT SYSLIST-... is issued, 
the user cannot expect to be given control in the STIXIT task each time 


he issues PUTX. 
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RELSE CLOSE BLOCK «TYPE Ro 


The RELSE macro causes 
- (with input files) the remaining records in the buffer to be skipped. 
- (with output files) the buffer that has just been processed to be cLosed 


and the next record to be written to a new buffer. 


Operation Operands 


fcbaddr 
RELSE 


(1) 
fcbaddr This operand specifies the address of the FCB associated ὀ 
with the file to be processed (exit address). 


(1) The FCB address is Located in register 1. 


Programming notes: 


- If the file is opened in INPUT, REVERSE or UPDATE mode, the RELSE macro 
causes any records remaining in the buffer to be bypassed when the next GET 
macro is issued. 


- If the file is opened in OUTPUT or EXTEND mode, the RELSE macro causes 
the next record to be written as the first record of a new buffer 
vhen the next PUT macro is issued. 


- If the file is opened in UPDATE mode and a PUTX macro is issued, RELSE 
causes the entire buffer to be rewritten. 


- If the Last action macro issued vas RELSE, the RELSE macro is ignored. 
This condition overrules conditions 1 and 2 above. 
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SEIL POSITION FILE «TYPE R> 


The SETL macro is used to specifiy the position of the internal record 
indicator from which subsequent file processing is to start. 


Operation | Operands 


. [fcbaddr B 
SETL ζ,1Ε}7 
(1) R 
fcbaddr This operand specifies the address of the FCB associated 
with the file to be processed (exit address). b 
e (1) The FCB address is Located in register 1. 
B Positioning is to take place to the beginning of the file. 
E Positioning is to take place to the end of the file. 
R The positioning information is to be obtained from the 


retrieval field in the FCB. 


Programming note: 


An illegal SETL operand causes control to be passed to the USERERR address 
of the EXLST macro. 
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6.5 ΕΗ! «EVANESCENT ACCESS METHOD» 


EAM is the access method for temporary files in BS2000. 
EAM has the following characteristics: 


e EAM files are not cataloged. Consequently, opening an EAM file does not 
involve disk access. 


e An EAM file is automatically erased after completion of the job which 
opened it (temporary file). 


e Communication between EAM and user can take place only via the EAM 
control block (MFCB, or Mini-FCB). Modification of the MFCB at file 
opening time is not catered for. 

€ No Label processing or storage space allocation takes place. 

e EAM uses only public volumes. 

e Space requirements for EAM routines and delays occurring during read/ 
write access operations are Less than with the standard access methods 
for cataloged files (UPAM, SAM, ISAM). 


e An EAM file can be processed by one job only (no shared file update). A 
single job can, however, open and process several EAM files. 


e EAM transfers blocks which are 2048 bytes in Length. In the case of / 
chained 1/0, up to 16 consecutive blocks can be processed with one macro. 


e EAM files are not supported by the checkpoint/restart routines of the 
system. 


6.5.1 EAM Functions 


EAM can perform the following operations: 

- Set up and open a new file. 

- Reopen an existing file. 

- Read (sequential or direct). 

- Write (sequential or direct). 

- Check for termination of an I/O operation. 

- Check and wait for termination of an 1/0 operation. 

- Close a file. 

- Erase a file. 

A particular operation is selected by specifying a hexadecimal code 
(operation code) in the MFCB. The EAM macro serves to initiate the 
specified operation. The effect is determined by the MFCB fields which EAM 


additionally evaluates after it has identified the operation code. 
Table 6-10 summarizes the EAM functions. 
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MFCB fields] Oper- |Option|Logi- Address 
byte of I/O 
area 2 


Operation 


Five|Sense|Sta-|Address|Number 
name|byte |tus 
byte|area 
S i 


Create and open E 

new file 

Reopen existing E+ τ Ε 

file 

Read E i 

Write E a 
e Check E 4 

Check and wait E. i 

Close file E i 

Erase file E i 


Table 6-10: EAM functions 


E: Contents of field are evaluated 

S: Contents of field are set 

i: Contents of field are ignored 

+: For exceptions affecting object module files, refer to section 8.5.3, 
"Programming Notes" 

=: For exceptions, see description of field 
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6.5.2 EAM Macro (Type R) 


There is only one supervisor call (SVC) with which to invoke EAM. The 
operation to be performed is defined by the contents of the MFCB. 


Operation Operands 


mfcbaddr 
EAM 

(1) 
mfcbaddr This operand specifies the address of the MFCB. 
(1) The address of the MFCB is Located in register 1. 


Description of the MFCB fieLds 


The MFCB is the communication area between EAM and the user. The field 
organization is shown in Table 6-11. 


The MFCB must be aligned on a word boundary. 


Field description Symbolic field name 


Operation IDMFOPC 
Option byte IDMFOC 
Logical block number IDMFLBN 
File name IDMFFN 
Sense byte IDMFEB 
Status bytes IDMFSB 
Reserved for system 

Address of I/O area 1 | ΙΡΗΕΙΟΙ 
Number of blocks to be IDMFNHP 
transferred 

Address of 1/0 area 2 IDMFIO2 


Table 6-11: MFCB field organization 


The MFCB can be provided with symbolic names by means of the IDMCB macro. 
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Operation codes 
- Create and open a new file - DMFO 


EAM assigns a file name (binary number in the range 1 - 14000), 

creates several entries in its own tables, and checks the option byte, 
the size of the I/0 area and the MFCB address. 

Exceptions affecting object module files are described in section 
6.5.3, "Programming Notes". 


- Reopen an existing file - DMFRO 


The option byte and the size of the I/O areas are rechecked. 

In this case, the Logical block number can be set by EAM to either 
beginning or end of file, depending on the value of bit 2! in the 
option byte. 


- Read - DMFRD 


Chained input: 


This read mode is specified by setting bit 2? in the option byte. 

The number of blocks read will be as specified in the field "Number of 
bLocks to be transferred". 

The field “Logical block number" specifies the first block to be read; 
a specification of Q0 causes blocks to be read which immediately follow 
the Last block referenced (sequential processing). 

in the case of chained input, it may be the case that one or more 
referenced blocks are Located beyond the end of the file. 

In this case the remaining blocks belonging to the file are 
transferred, the number of blocks involved being entered in the field 
"Number of bLocks to be transferred", and either bit 2? or 29 being 
set in the error byte. The number of blocks transferred can be 0. 


Non-chained input: 


This read mode is specified when bit 2? in the option byte is not set. 
Either the block with the specified block number is read, or the bLock 
following the Last block referenced is read (Logical block number = 0; 
sequential processing). 


= Write - DMFWR 


Chained output: 


This output mode is specified by setting bit 2? in the option byte. 
The number of blocks written will be as specified in the field 

"Number of bLocks to be transferred". 

The field "Logical bLock number". specifies the position in the file to 
which the first of a series of blocks is to be written; specifying 0 
in this field causes blocks to be written directLy following the end 
of the five. 


Non-chained output: 


This output mode is specified when bit 2? in the option byte is not 
set. 

A block is written to the position specified in the field "Logical 
bLock number"; specifying O in this field causes a block to be 
written directly following the end of the file. 
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- Check - DMFCK 


A check is performed as to whether the Last 1/0 operation has been 
compLeted. 

If the Last I/O operation has terminated, the status bytes are 
transferred to the MFCB. 

If the Last I/0 operation has not yet been completed, register 15 is 
set to X'00000008'. 

Whatever the case, control is immediately returned to the user. 


- Check and vait - DMFCW 
CompLetion of the Last I/O operation is avaited, and the status bytes 
are subsequentLy transferred to the MFCB. 
If the transfer of the status bytes has already been implemented by 
another operation, the current operation has no effect. 

- Close five - DMFCL 
The file is closed but not erased. 
The block number of the Last block in the file is placed in the field 
"Logical bLock number". 

- Erase file - DMFER 


The file is erased whether it is open or not. 


e Option bytes 


EA 
2 This bit is evaluated when reading and writing. 
=Q I/O area 1 is to be used. 
=1 I/O area 2 is to be used. 
1 
2 This bit is evaluated when reopening a file. 
=0 The Logical block number of the Last bLock belonging to the 
file is placed in the field “Logical block number". 
=1 The value zero is placed in the field “Logical block 
number". 
2 
2 This bit is evaluated when opening and reopening a file. 
Ξ0 Chained I/O is not to be used. 
=1 Chained I/O is to be used. 
3 
2 Reserved 
& | 
2 This bit is evaluated when opening and reopening a file. 
Ξ0 The file to be opened is not the object module file of the 
calling job. 
-1 The object module file of the calling job is opened. 
5 7 


ε.α Ἡ Reserved for use by the system. 
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e Logical block number 


The Logical block number is a 2-byte binary number which indicates the 
block within the file which is to be read or written. 


In the case of chained I/0, the binary number denotes the first in a 
series of blocks to be read or written. 


The value of this binary number can be in the range 1 - 65535. 
The value 0 specifies sequential processing: 


- In the case of reading, the block which directly follows the Last 
block referenced (in a read or write operation) is transferred. 


- In the case of writing, a block is added to the end of the file. 


- In the case of chained I/O the same applies by analogy to a series of T 
6 blocks instead of to a single block (see also operation code: 
Read - DMFRD). 


Each block contains 2048 bytes. Any record structure within a block 
remains unknown to EAM (same as with UPAM). 


e FiLe name 


The file name is a 2-byte binary number which is placed in this field by 
EAM when a new file is opened. This number must be specified whenever 
the file is subsequently referenced. 


The value of the binary number is restricted to the range 1 - 14000. 


e Sense byte 


If an operation could not be successfully executed, this field wilt 
contain an indication of the cause; in this case, EAM sets register 15 
to X'00000004'. After normal execution of an operation, register 15 
contains X'00000000'; the sense byte is set to X'OO'. 


e | The bit positions of the sense byte have the following meanings: 
Ό 
2 Illegal operation: 


= Illegal operation code 


- An existing file is not open and an attempt was made to 
close the file or to perform a read/write operation. 


- MFCB is not aligned on a word boundary. 
2 
- Bit 2 in the option byte is set (chained 1/0) and the value 
in byte DMFNHP (number of blocks to be transferred) is not in 
the range 1-16. 


"a Illegal file name: 
- The file name is not in the range 1 - 14000. 
- The file does not exist. 
© - The file does not belong to the calling Job. 
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2 
2 ILLegaU block number: 
- A read operation has been requested which refers explicitly 
(i.e. block number + 0) to one or more blocks Located beyond 
the end of the file. 
- A write operation has been requested with a block number 
greater than: ' 
(number of Last block in file) + 1. 
J 
2 Illegal I/O area: 
- Illegal address of an 1/0 area. 
- One of the I/O areas is too small. 
4 
2 EAM space is not available. 
- The number of EAM files in existence has already reached the 
maximum of 14000 (upon opening a file). 
- The number of occupied disks of all EAM files of the system 
has reached the maximum of 193,536. 
5 
2 A non-priviLeged program is attempting to process a privileged 
five. 
6 
2 A read operation has been requested which refers implicitly 
(i.e. bLock number - 0) to one or more bLocks beyond the end of 
the file. 
7 
2 The Last I/O operation requested, or the preceding one, was 


unsuccessful. The status bytes should be checked to determine 
the cause of the error which has occurred. 


- Error on starting the Last I/O operation requested. In this 
case, all 5 status bytes contain the value X'00'; a check 
operation performed immediately afterwards has no effect. 
In this case, hovever, the preceding I/O operation has been 
successfully compLeted (otherwise the Last I/O operation 
requested would not even have been started). 


- In all other cases (i.e. at Least one status byte # 0), an 
error occurred in the preceding I/O operation; the status 
bytes then contain additional information concerning the 
error. 

The Last I/O operation requested vas not started. 
e Status field 


This field is set only if the following conditions are simultaneously 
satisfied: 


- The preceding operation vas a read or write operation. 


- The current operation is a read, write, check, check-and-vait, or 
cLose operation. 
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The following bytes are transferred from the Channel Control Block (CCB): 
- Standard device byte 
- 3 sense bytes 


- Executive flag byte (cf. Appendix A.3) 


e Address of I/O area 1 


This field contains the virtual address of the first byte of 1/0 area 1. 


In write operations, a block is transferred from this area to the five; 
in read operations, the process is reversed. 

With non-chained I/0, the area must be Located in a virtual page and 
be aligned on a word boundary. 


In the case of chained I/0, the area must be aligned on a page boundary 
and must be abLe to accommodate at Least as many bLocks as are to be 
transferred. | 


e Number of blocks to be transferred 


This is a 1-byte binary number in the range 1-16. This field is evaluated 
upon opening or reopening a file only if chained 1/0 is specified in the 
option byte. 


In the case of chained I/O and upon reaching end of file in read 
mode, the number of blocks transferred is contained in this field (see 
also operation code: DMFRD). 


e Address of I/U area 2 


This field contains the virtual address of the first byte of 1/0 area 2. 
This address may be the same as that for I/O area 1. Hovever, if chrono- 
Logically overlapping processing is to be performed, this field must 
contain the address of an area which does not encroach onto I/O area 1. 
The conditions affecting I/O area 1 also apply here. 


6.5.3 Programming Notes 


9 Use of check operations 


After a read or write call, control is returned to the user as soon as 
the requested operation has been accepted. In other vords, this operation 
does not need to have been compLeted. 


However, before a read or write operation is accepted, completion of the 
previous read/write operation (if any) is awaited (with an implicit 
check~and-wait operation). 


Similarly, completion of the Last read/write operation is awaited if a 
close operation is requested. 


Thus, a check operation is necessary only after the Last in a series of 
read/write operations if the file is not immediately closed again or if, 
in the case of chained I/0, reading is continued until the end-of-file 
condition is reached (bit 2? or 28 in the sense byte - 1) and the number 
of blocks transferred is not equal to 0. 
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ExampLe: 


- 3 read operations are performed in an EAM file. The file is not 
subsequently closed, as it is still required for Later input/output 
operations; however, these I/O operations are not requested until the 
bLocks which were read have been processed: 


READ 

READ 

READ 

CHECK /WMAIT Termination of the previous I/O operation 
. is avaited. 


Processing of the bLocks read 


Further 1/0 operations 


- A read operation with chained I/O is performed from an EAM file (6 
bLocks at a time). Bit 2? is set in the sense byte. 


The field "Number of blocks to be transferred" now contains, for 
instance, the value X'02', i.e. of the 6 blocks requested, only the 
first two belong to the file, and only those two are transferred. 
In this case, one of the following operations must be requested: 


A check-and-vait operation, or 
a close operation. 


In both cases, termination of the read operation is awaited and the 
status bytes are placed in the MFCB. 
Changing the input/output mode (i.e. chained or non-chained 1/0), the 


addresses of the I/O areas and the number of blocks to be transferred. 


Upon opening or reopening a file, the following information is saved in 
system memory: 


- Addresses of the I/O areas 
- Number of blocks to be transferred 
- I/O mode 


If any of this information is to be changed during processing of the 
file, the following sequence of operations is required: 


1. Close file. 

2. Modify fields in MFCB. 

3. Reopen file. 

The number of blocks to be transferred should be altered, for example, if 


fewer blocks are to be transferred with the Last write operation than was 
specified when opening the file. | 
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ExampLe: 


99 blocks are to be written to an EAM file; 15 is selected as the number 
of blocks to be written by one EAM call (byte DMFNHP in the MFCB). 


The following operations are then requested: 


OPEN (new file) 


WRITE After these operations have been 
WRITE performed, only 9 blocks remain to be 
WRITE written. Therefore, the file must be 
WRITE closed and reopened, with the value 9 
WRITE for the number of blocks to be 
WRITE transferred. 
CLOSE 

e REOPEN 
WRITE 
CLOSE 


e Overlapped input/output 


A reduction in processing time can be achieved by means of the parallel 
execution of user job and I/O operations. 


While a portion of the data in a file is being processed, a further 1/0 
operation can be executed. Two 1/0 areas must be employed for this to 
be possible. 


The following example illustrates the overlapping of processing and rs 
operations. 
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START 


UL: -L,END-OF -FILE: ΞΝΟ 


End-of- =) 


END-OF-FILE:-YES 


PROCESS bLock UL-1 


IF END-OF-FILE-YES, TERMINATE 


L:=Lt1 


End-of-file? 


END-OF -FILE:-YES 
PROCESS block L-1 


IF END-OF-FILE-YES, TERMINATE 


Fig. 6-9: Overlapped input/output 
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e Sequential read with chained input/output 


Chained I/0, when used in conjunction with sequential reading, is most 
efficient if: 


- a multiple of 3 is selected as the number of blocks to be transferred 
(e.g. 35 6, 9, ...,2.ῃΠροοο}} 


- the block number selected is in the form 
(multiple of 3) + 1 
(e.g. e E^ 4, 7, eee y S*ENt*1 secede 


e Handling object module files using EAM 
4 
Each job can process exactly one object module file. If bit 2 in the 
option byte is set, all operations relate to the object module file. 


The actions involved in opening or reopening a file are illustrated in 
the following diagram: | 


DETERMINE TYPE OF OPERATION 


Reopen existing 
file (Χ'017) 


Open new file 
(X"OO") 


» Does file exist? ~ 


Assign file name 
EXISTS EXISTS 
Set Logical block 


RETURN to user program 


Does file exist? 


* 
Set bit 2 of 
sense byte to 1 


Fig. 6-10: Actions involved in file opening 
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FILE EXISTS 


Place file name in MFCB 


Positioning to start of five 
1 
(option byte bit 2 =1)7 


Set bLock number in MFCB Set bLock number in MFCB to 
to O number of Last block in file 


Fig. 6-11: Procedure for opening the object module file 
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A APPENDICES 


R.1 COMMAND AND MACRO CONVENTIONS 


Commands 


ALL BS2000 commands are similar in structure. They all begin with a slash 

(/) which identifies them for both system and user as commands. In 

interactive mode, the system provides the slash; in batch mode, it is 

entered by the user in the first column of each Line or card belonging to 

the command. The slash is followed by various entries, which may be divided 
e into four fields: 


< Command 


The IDA commands constitute an exception to this, as several such commands 
—_" IDA statement 


may be combined to form an IDA statement: 
name 


«— ——— IDA command ————————————» <— IDA command ------------» 


© Name field 


Purpose: The command or statement name specifies the symbolic address 
which may be used as a branch destination in other commands. 
Additionally, a statement name in an AT command (IDA) identifies 

the IDA counter. 


The user can decide whether or not to give the command a name. 
(For this reason, this name is not usually referred to in the 


descriptions of the commands, although a name can be assigned 
to each command. ) 
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Structure: 


The name field may commence with any number of blank characters 
(X'40'0. A period marks the start of the name proper. This period 
is followed by an alphabetic character, and this, in turn, may be 
followed by up to 7 alphanumeric characters. A blank may appear 
at the end. 


ExampLes: 
fe NAMELI ce eee 


| eerie SP » ATA 


Te A1234567. 995999 


Operation field 


Purpose: 


Structure: 


The operation to be performed is specified by the command name or 
its abbreviation. This field must therefore be included in all 
commands. 


The operation field can commence with any number of blanks 
(X'40'0. If there is a name field, it must be separated from the 
operation field by a blank. If no name field is included, the 
command name or its abbreviation can immediately follow the 
slash. 


Examples: 
/STATUS 


fa NAME ouuu STATUS 
/. X STEP 


Operand fieLd 


Purpose: 


Structure: 


A1-2 


The operands of a command define the various functions of that 
command. 


A distinction is drawn between positional operands and keyword 
operands: 


- Positional operands are defined by their position in the 
command and must therefore be entered in the prescribed order. 


- Keyword operands are defined by a keyword (KEYWORD=) and may 
thus appear in any order. 


The first operand in this field must be separated from the 

command name in the operation field by at Least one blank 

X('*40*). The commas used to separate individual operands can be 
preceded or followed by any number of blanks, as can the equals 
signs within keyword operands. This applies also to the separating 
characters , 3 : () = + - * / < > in IDA commands. 
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Examples: 
/PRINT DATA positional operands 
/. NEUMANN CATALOG ΝΑΜΕΙ  ,NAME2 
/FILE.LINK-ZCHAIN,DEVICE-TAPE keyword operands 
/ COMPILE PARAM ERRFIL=YES 
/ERASE FILE ,DATA,LIST=YES 2 positional operands, 


1 keyword operand 


/DISPLAY X3 :%7 2 positional operands 
in IDA commands 


Comments field 


Purpose: Any further information which the user may wish to include 
regarding the command may be entered in the comments field, as 
this field is not interpreted by the system. Such comments are 
optional. 


Structure: The comments field may commence with blanks (X'40'). The actual 
comments must be enclosed within double quotation marks ("), and 
may include all characters except the quotes symbol itself and the 
ETX character. Such comments can be appended to the operand field, 
or inserted either before or after the comma separating operands. 


ExampLes: 


Incorrect use: 

/FSTAT ***"FILE STATUS FOR ALL FILES"xxx" 
Correct use: 

/.PURPOSE EXECUTE PROG "TEST PROGRAM NO.5” 


Continuation Lines 


A command can consist of one or more Lines. In the case of punch cards, each 
card corresponds to a Line. 


The hyphen serves as a continuation character, i.e. it indicates that there 
is a continuation Line. The number of continuation Lines allowed depends on 
the continuation mechanism (system parameter SSMCOPT at system generation 
time). See section 1.2 in the "Control System Command Language" manual. 


The first operand of a command must be entered in the first Line. 


Interactive If the command is entered at a terminal, the continuation 

mode: |» character can appear anywhere within a Line and must be 
immediately followed by the ETX symbol. The system responds 
with the slash for the next continuation Line. 


Batch mode: In batch mode, the continuation character must appear in 
coLumn 72 of the Line or card. The remainder of the record 
(columns 73 through 80) is then ignored. The user himself 
must enter the slash in column 1 of each Line or card. 
Procedures (interactive and batch mode): 
Continuation Lines in procedure files are subject to the same 
ruLes as for batch mode. 
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Examples: 


Interactive 
mode: 


Batch 
mode: 


A1-4 


Line 1: /FILE FILENAME,-< 
Line 2:  /LINK-DSET10, "LINKNAME"-« 
Line 3: /DEVICE=TAPE,FCBTYPE=SAM < 


"X" represents the ETX character. 

Line 1:  /PROCEDURE C,(&A,&COMPIL=, " 
Line 2:  /&PASSW-C'AD',PROG,£AB1) nd 
Line 3: /,SUBDTA=*"SYMBOL FOR PROGRAM" < 


The hyphen "-" must be given in column 72 in 
Lines 1 and 2. 
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Macros 


Macro instructions are processed by the Assembler using macro definitions 
supplied by Siemens. Macros are written according to the conventions 
described below. 


The processing of a macro instruction by the Assembler is called the 
expansion of the macro instruction. The expansion results in data fields 
and executable instructions. The data fields, called operands, specify the 
Operation to be performed and are contained in either registers (operand 
registers) or data areas (operand Lists). 


- If the operands are contained in registers, only registers 0 and 1 may be 
used. 


- If the operands are contained in an operand List, the address of this 
List is pLaced in register 1 and referenced by the service routine 
called. 


The macro instruction Language 


Macro instructions, Like AssembLer instructions, are written in the 
following format: 


Name field 


Operands 


0P1,0P2,... 


The name field of the macro instruction may contain a symbol or be Left 
blank. Normally, this symbol is the name associated with the first 
executable instruction of the macro expansion. 


Operation field 


The operation field contains the mnemonic operation code of the macro 
instruction. This code may be a string of not more than eight alphanumeric 
characters, the first of which must be a Letter. User macro names should not 
begin with a dollar sign ("$"), since privileged system macros begin with 
this character. 


Operand field 
The operand field may contain no operands, one operand, or several operands 


separated by commas. There are two types of operand: positional and 
keyword. 
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Positional operands 


When three or fewer operands are required by a macro instruction, positional 
operands are generally used. Positional operands must be written in a 
specific order, e.g.: 


EXAMPLE A,B,C 


At assembly time, the order in which operands A, B and C are processed is 
determined by the order in which they appear. If the second operand (in this 
case: B) is omitted, the user must supply the second comma so as to maintain 
the position of the third operand. The positional field should contain no 
blanks (X'40')0, e.g.: 


EXAMPLE Α,,ς 


If the Last operand is to be omitted, the delimiting comma need not be 
written. For example, if the operands B and C are to be omitted, the macro 
instruction could be written as folLlovws: 


EXAMPLE A 
Keyword operands 


The keyword associated with a given keyword operand uniquely identifies that 
operand to the Assembler. Therefore, these operands can be written in any 
order. A keyword operand is written as a keyword, as defined in each macro 
instruction description, immediately followed by an equals sign and its 
value, e.g.: 


EXAMPLE AREA=X,LENGTH=100 
Mixed operands 


An operand field may contain both positional and keyword operands; however, 
all positional operands must precede all keyword operands, e.g.: 


EXAMPLE A,B,C,AREA=X,LENGTH=100 


The rules governing the omission of positional and keyword operands apply 
also to mixed operand fields. For example, if the operands B, C, and AREA 
are to be omitted from the above example, it must be written as follows: 


EXAMPLE A,LENGTH=100 
Operand sublists 


A subList consists of one or more positional operands, each separated by 
commas and the total List enclosed in parentheses. 

The entire subList is considered to be one operand in the sense that it 
occupies a single position in the operand field or is associated with a 
Single keyword. The contents of the sublist are processed similarly to 
positional operands. The following operands are sublists: 


(A,B,C) 
(A) 


In the second example, the subList consists of only one operand. If a macro 
instruction description shows that an operand is to be written as a subLlist, 
the enclosing parentheses must be written, even if there is only one element 
in the sublist. 
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Macro description notational symbols 


Notational symbols in the operand fields of macro instruction descriptions 
assist the user in showing how, when, and where an operand is to be 
written: 


The notational symbols are: 


1. 


2ο 


© 3. 


es 


5. 


6. 


Braces |l 
Square brackets [] 


Underscore 
ELLipsis, shown as... 


Braces denote operand grouping. They are used primarily to group 
alternative operands, e.g.: 


ke | 
OUTPUT 
Square brackets denote options. Information enclosed in square brackets 


may either be omitted or written in the macro instruction, depending on 
the requirements. 


Example: 


Operands 
LNPUT 
ή ha 


OUTPUT 
The user has 3 options for the operand entry, i.e. to specify: 


Csymbol] 


- no operand 
=~ ΤΝ 
= OUTPUT 


An underscore indicates a default value that is assumed by the system if 
the user specifies no operand. In the above example, INPUT is the 
default value. 


The ellipsis denotes the optional occurrence of the preceding 
syntactical unit one or more times in succession. A syntactical unit is 
any combination of operand representations, commas and notational 
Symbols enclosed in square brackets. 


Uppercase (capital) Letters must be entered by the user exactly as shown 
in the macro description. For example, the operation and the coded 
values in the operand field must always be specified in uppercase 
Letters. 


Commas and parentheses must be written as shown in an operand field. 
They are delimiters, not notational symbols. 
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Macro description value mnemonics 


Value mnemonics give the user a brief description of what the form of a 
particular operand should Look Like. The following 11 value mnemonics are 
used in this manual: 


- relexp 

- addr 

=- exit-addr 
- addrexp 

- integer 

- absexp 


- value 
- text 

- code 

- symbol 
= chars 


In the format, only the positional operand is supplied. The particular form 
of the operand (value mnemonic) can be obtained from the description. 


Example: 


Operands 


EXAMP 


Each keyword operand is defined by the keyword, an equals sign and a value. 
The particular form of the value is contained in the description of the 
operand, e.g. "(vaLue)". 


[symbol] 


ExampLe: 


EXAMPT 


For each value mnemonic, one or more operand forms is permitted. For 
example, the value mnemonic "reLexp" denotes that a relocatable expression 
can be written as the operand form; whereas the value mnemonic "addrexp" 
specifies that an explicit or implicit address must be written. 


Operands 


Csymbol] KEYWI=value 


The following 11 operand forms are used: 


- relocatable expression (relative expression) 
- register notation 

- explicit address 

- implicit address 

=- symbol 

- decimal integer 

- absolute expression 


- code 

- text 

- characters 
=- oplist 
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Fig. A.1-1 illustrates the value mnemonics and their permissible operand 
forms. 
The operand forms are described on the pages following this table. 


Code| Text] Cha- 
rac- 
ters 


reLexp 


addr 


exit- 
© addr 


addrexp 


text 


code 


symbol 


chars 


Fig. A.1-1: Macro convention operand forms 


Wote: 


- An X indicates that the operand form may be written. 
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ReLocatabLe expression 

A relocatable expression is one whose value would change by n if the program 
in which it appears were relocated n bytes away from its originally assigned 
area of storage. ALL relocatable expressions must have a positive value. A 
relocatable expression may contain relocatable terms ~~ alone or in con- 
junction vith absoLute terms -- under the following conditions: 

1. There must be an odd number of relocatable terms. 


2. ALL relocatable terms but one must be paired. Pairing is described under 
"AbsoLute expression" below. 


3. Any unpaired term must be directLy preceded by a minus sign. 
4. A relocatable term must not occur in a multiply or divide operation. 
Example? 


In the following examples of relocatable expressions, SAM, JOE and FRANK are 
in the same control section (CSECT) and are relocatable; PT is absolute. 


SAM 

SAM-JOE*FRANK 

JOE-PT*5 

SAM*3 

SAM-JOE is not relocatable, because the difference between two relocatable 
addresses is constant. 

Register notation 

Register notation is written as an absolute expression enclosed in 
parentheses. When computed, the absolute expression must Lie between 2 and 


12 so that the corresponding general register can be referenced. 


In the following examples of register notation, SAM and JOE are relocatable 
and PAL is absolute. 


(5) indicates general register 5 
(SAM-JOE) 

(PAL) 

(PAL 5) 

ExpLicit address 


The expLicit address is vritten in the same form as an AssembLer Language 
operand, i.e.: 


a(b,c) 


—» Base register 
» Index register 


> DispLacement 
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Examples of explicit addresses: 


2(0,5) 
0(2,4) 


Implicit address (indexed) 


An implicit address is written as a symbol, optionally indexed by a 
specified index register. 


Examples of implicit addresses: 


GUPOFF 
ALPMAY (4) 


Symbol 


The operand is written as a string of up to eight alphanumeric characters, 
the first of which is alphabetic. Embedded commas and blanks (spaces) in the 
string are not permitted. Symbols beginning with a dollar sign ("$") must 
not be used. The symbols beginning with this character are reserved for 
system use. 


Examples of symbols: 


LEE 
BILL8SAM 
DESDEB 


DecimaL integer 


The operands may be written as a whole decimal number of up to 8 digits, e.g. 
5, 31, 127 etc. 


AbsoLute expression 


© An absolute expression may be an absolute term or any arithmetic combination 
of absolute terms. An absolute term may be an absolute symbol or any of the 
self-defining characters. ALL arithmetic operands are permitted between 
absolute terms. 


An absolute expression may contain relocatable terms - alone or in combination 
with absoLute terms - under the following conditions: 


1. There must be an even number of reLocatabLe terms in the expression. 

2. The relocatable terms must be paired. Each pair of terms must have the 
same relocatability attributes, i.e. appear in the same control section 
of an assembly. Each pair must consist of terms with opposite signs. 


The paired terms need not be contiguous, e.g. RT*AT-RT, where RT is 
reLocatabLe and AT is absolute. 
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3. A relocatable term must not occur in a multiply or divide operation. 


The pairing of relocatable terms (with opposite signs and the same 
relocatability attributes) cancels the effect of relocation. The values 
represented by the paired terms remain constant, regardless of program 
relocation. For example, in the absolute expression 


A-Y*X 


A is an absolute term, and X and Y are relocatable terms with the same 
relocatability attribute. If A equals 50, Y equals 25 and X equals 10, 


the vaLue of the expression is 35. 


If X and Y, hovever, vere to be 


reLocatabLe by a factor of 100, their values would then be 125 and 110. 
However, the value of the expression would still be 35, since 50-125 


*110 - 35. 


An absolute expression reduces to a single absolute value. 


In the following examples of absolute expressions, JOE and SAM are 
relocatable and defined in the same control sections; BERNY and DAVE are 


absolute: 


331 

DAVE 

BERNY *DAVE-83 
JOE-SAM 
DAVE+4+BERNY 


Code 


ExampLe: 


Operands 


Lsymbotu] FTBAL scores, 


Code is written exactly as defined in the description of the macro 


instruction: 


HT Half time 
FT Full time 


The macro instruction should be written in a program as follows: 


SAM FTBAL HT 
FTBAL FT 


Text 


A text operand is written as a string of alphanumeric characters enclosed in 


Single quotes('0). Embedded blanks (X'40') 
If a single quote or a pLus sign is to be 
these characters must be supplied in each 
the encLosing quotes, must not exceed 255 


'"AREA,PCB,132','1256' 


A1-12 


and special characters are permitted. 
used in the string, then 2 of 

case. The text operand, including 
characters, e.g.: 
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Characters 


Character operands are written as a character string. Embedded commas or 

blanks (X'40') are not permitted. If a single quote or plus sign is to be 
used in the string, 2 of these characters must be supplied in each case. 

The character string need not be encLosed in quotes, Ce Ge: 


CUBTDAVE+HEINZ+JOHN+830PMOT 


OpList operands 


In several macro descriptions the operand field is specified as: 


text 
opList- 


addr 


This implies that a List of keyword and/or positional operands can be 
written as fields of a character string and that the character string itself 
(encLosed in single quotes) or the address of the string can be written as 
the opList operand, depending on whether the "text" or "addr" form of the 
operand is chosen. 


If oplist is presented as a character string, i.e. the "text" form was 
specified, the macro expansion places it in the assembled program followed 
by an end-of-message code, and Loads a pointer to the string in register 1. 


If opList is given as an address. i.e. the "add" form vas specified, the 

expansion pLaces this address in register 1. In this case, the programmer 
must define the operands vithin his program and provide an end-of-message 
code. 


To reference opList macro operands in order to change the code, the address 
option of the macro is used; it is permissible to define the operand string 
as a series of adjacent fields, each with its oun Label. 


The string must end with a hexadecimal 27, which serves as an end-of-message 
code. Any unused space within the fields of the string must be filled with 
blanks (X'40') to the maximum size of that field. Unlike other operand 
forms, all commas in an oplist operand must be written, even if no values 
are specified. 


A typical operand string might be coded as follows: 
OPLIST DC C'first operand’ 
OPLIST1 DC C*,second operand’ 
OPLIST2 DC C',nth operand’ 
DO πο 
Types of macro instruction 


Most system macro instructions are of two basic types: 


R-type (register) or 
S-type (storage) 


The name of each macro description in this publication is followed by a type 
indication (R, S or 0). Macro instructions which are neither R-type nor 
S-type, referred to as other macro instructions, are denoted by (0) in their 
descriptions. 
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R-type macro instructions 


Address operands in R-type macro instructions are always classified as 
"exit-addr" or "addrexp". This arrangement allows the user to employ indexing 
although the addresses transferred in R-type macro instructions are property 
created, i.e. the base register used for the addresses passed must contain 
the proper value, in order to ensure that the address refers to the desired 
Location in virtual storage. 


ExampLe: 


Assume an R-type macro instruction RTYPE, which expects an address "area" in 
register 1 and the "Length" of that area in register Ο. Its macro 
description would be as follows: 


RTYPE 


Operands 
mur ns 
5 
(1) (0) 


SpeciaL register notation 


[symbou] 


The user's program can be written so that one or both of the operands 
already exist in the correct operand register when the macro instruction is 
executed. In this case, (1) or (0) is vritten as the operand. The notation 
(1) or (0) is referred to as special register notation. Registers (1) and 
(0) cannot be used in a macro instruction unless special register notation 
is shown in the macro instruction description. 


S-type macro instructions 

An S-type macro instruction is used vhen the number of operands to be trans- 
ferred to the calling routine cannot be contained in the two operand 
registers. The operands are placed in an operand List whose address is 
transferred to the calling routine in register 1. 

There are three forms of the S-type macro instruction: 

le the standard form 

2. the L-form (operand List only) 


3j. the E-form (executable code only) 


ALL S-type macro instructions are of the L-form and E-form unless otherwise 
stated under the individual descriptions. 
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S-type - standard form 


The standard form of the S-type macro instruction generates both the operand 
List required by the calling routine and the Linkage to that routine. 


Address operands in the standard form of the S-type macro instructions are 


always Classified as "addr". Consequently, they must not be indexed, and the 
user program is not responsible for maintaining the transfer registers. 


Example: 


Assume an S-type macro instruction called STYPE, which expects the addresses 
of two areas, "input" (exit-addr) and "output" (exit-addr), as well as the 
"Length" (value) of these areas. The macro description would then be as 
follows: 


Operation 


STYPE 


Operands 


[symbol] input ,output,lLength 


S-type - L-form 


The L-form macro instruction is used to create an operand List. E-form macro 
instructions are used to point to the operand List that is generated by the 
L-form macro instruction. 


The AssembLer recognizes an L-form macro instruction by the presence of the 
keyword operand MF=L in its operand field. 


Because the L-form macro instruction generates only an operand List, the use 
of operand types which require executable codes, such as register notation, 
is prohibited. 


There is an internal difference in the kinds of operands required in the 
macro description, when using the various forms of the S-type macro 
instruction. 


If the standard form indicates operands Like "addr" or "value" (i.e. register 
notation is allowed), it is implicitly understood that L-form macro 
instructions allow only operands Like "reLexp" and "absexp", i.e. register 
notation is not allowed. 


Therefore, the L-form macro STYPE described above would become: 


STYPE 


The name field is required in the L-form because it usually becomes the 
Label of the generated operand List and is referred to by the E-form macro 
instruction. 


Operands 


[symbol] input ,output,value,MF=L 


The L-form macro instruction generates the operand List at the place the 
macro instruction is encountered. As the L-form expansions contain no 
executabLe code, the List should be placed in the program area which 
contains DS (Define Storage) and DC (Define Constant). 
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S-type - E-form 


A generated operand List may be referred to by an E-form macro instruction. 
The AssembLer recognizes an E-form macro instruction by the presence of the 
keyword operand: 


List 
MF=(E, ) 

(1) 
in its operand field. 
"List" specifies the Location of the operand List to be used by the 
E-form macro instruction. If (1) is written, register 1 must be Loaded 
vith the address of the operand List before execution of the macro 
instruction. The symbol in the name field of an L-form macro instruction 


becomes the name of the operand List. 
Consequently, the above E-form macro STYPE would have this format: 


STYPE 


Operands 


List 
) 


[symbol] 


Other macro instructions 


Certain system macro instructions cannot be classified as either R-type or 
S-type; they are referred to simply as other macro instructions, denoted by 
(0) in the macro descriptions. 


Error codes 


Macros which return error codes in registers must place the codes in the 
Loy-order byte of register 15; the Leftmost three bytes are set to zero. 


Zero in the Lov-order byte means that no error occurred. Otherwise, the 
error code would be a multiple of four (to facilitate indexing). 


Exception: 


The data management macros (service macros and access methods) place the DMS 
error code in the ID1ECB field of the P1FCB. 

The file management macros (CATAL, ERASE, ee.) use the two Lovest-order 
bytes in register 15. 


LiteraLs 


Macros may generate Literals. In macros where the user is responsible for 
maintaining the registers for operands, he must also ensure that the 
Literals are generated. Conversely, where the user does not have to Load the 
registers, the Literals are generated by the macros. 
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8.2 DNS DSECTS «DUMMY PROGRAM SECTIONS> 


JSECTs of DMS tables, operand Lists, FCBs and Catalog entries are available 


to user programs by means of macros. The names and sizes of the component 
fields are also defined; however, the arrangement of the sections is subj 
to change. | 


The macro name and a brief description of each DMS DSECT is given in Tabl 
A.2-1. Only those DSECTs of immediate interest to users are Listed. 


Any user interested in the current expansion of a specific DSECT can use 
the following macro. 


The format of the call is: 


Operation Operands 
macro name prefix 
Γ01ἱ{, J 
+ 
D This operand specifies that the macro is to generate the 
DSECT. 


Default value: The DSECT statement is not generated. 


prefix This operand specifies the single character prefix to be 
added to the beginning of all Labels in the DSECT. 


* This operand specifies that no prefix is to be used. 


Default vaLue: I 
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Macro name DSECT description 


IDCAT CATALOG (CATAL) operand List 

IDCE Catalog entry 

IDCEG Catalog entry, addition for file generation groups 

IDCEX Catalog entry extension 

IDCHA CHANGE (CHNGE) operand List 

IDCOP COPY macro operand List 

IDECB UPAM event control block 

IDEE Catalog entry, extent List 

IDEMS DMS error messages | 2 


This macro generates a List of EQUs describing the error 
messages of the DMS modules (see Appendix A.3, "DMS Error 


Codes") 
IDERS ERASE macro operand List 
IDFCB FCB (P1 section) 
Note: this DSECT describes all FCB formats 
IDFST FSTATUS (FSTAT) macro operand List 
DMAIMP IMPORT macro operand List 
IDMCB EAM control block 
IDOST File information about opened files of the user 
IDPFL FILE macro operand List 
IDPFX FILE macro operand extension 9 
IDPPL UPAM operand List 
IDREL RELEASE (REL) macro operand List 
| IDVRF VERIF macro operand List 
IDVT Volume Label entry à 
DMADR RDTFT information (when the LINK operand is specified) 
DMARD RDTFT macro operand List 


Table A.2-1: DMS DSECTs of interest to the user 
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8.3 DHS ERROR CODES 


Error codes contain all the necessary information about the errors affecting 
programs and tasks. From them the user can derive details of the type and 
origin of an error, as well as what action he should take. The error codes 
employed in the DMS offer the following advantages. 
e The abbreviated format permits the coding of many different. errors. 
e The coding permits identification of the source of the error. 
e In the case of recoverable errors, abnormal termination can be avoided 

by means of self-analysis by the program. 


Types of error 


- e DMS errors during program execution 


Error codes occurring in connection with file management macros (CATAL, 
CHNGE, COPY, ERASE, FILE, FSTAT, REL, VERIF) are stored in register 15 
(in the 2 Lowest-order bytes). 


Error codes which occur when using data management macros (service 
macros and access methods) are stored in the ID1ECB field of the ΡΊΕΟΒ 
(dispLacement X'98"'). 


In the case of errors occurring during program execution, the DMS 
analyzes the stored error code (via EXLST error exits). Either the error 
condition can be corrected by the program, or the program is abnormally 
terminated and an error message issued (SYSOUT for interactive mode, 
SYSLST for batch mode). 


® DMS command errors 


In the event of an error occurring when using DMS commands, a message is 
issued via SYSOUT. 


C In interactive mode, the user can enter the correct command. 


In batch mode, the program branches to the next STEP command or, if 
none exists, to the LOGOFF command. 


The message texts for all error messages can be retrieved from MSGFL 
(message file) by means of the error code. 


The message texts frequently contain blanks, these being intended for 
information specific to the particular error. 
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Error coding scheme 


DMS error codes have the following structure. 


> replaced by "D" upon output of DMS messages (x, y, z are 
| hexadecimal digits) 


» Error number 


y is the first component to 
detect the error; (Rule 1) 


x is the calling component 


Component x 
detected the (RuLe 2) 
error 


Fig. A.3-1: DMS error codes d 
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x y Components 

2 2 | Privileged PAM (PPAM) 

3 3 Catalog Manager (CMS) 

4 4 Data Storage ALLocator (ALLOC) 

5 5 Commands vith corresponding macros 
6 6 Commands without corresponding macros 
7 Privileged Tape Access Method (PTAM) 
9 UPAM 

A ISAM 

B SAM 

C BTAM 

D OPEN 

E CLOSE 


Table A. 35-1: Coded values of components 
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DMS error codes 


The order of the components identified by the hexadecimal numbers 2 (for 
PPAM) through E (for CLOSE) is not arbitrary. Rather it indicates that a 
component with a higher number can call a component with a Lower number (Cand 
not vice versa). 


Should an error arise in a called component, its error code is returned to 
the calling component and thus modified. 

Examples of the generation and modification of error codes 

1. One Level (error in the calling component) 


Assume that a user calls UPAM and the file is not open. UPAM would place 
error code 0994 in the FCB and exit via $GOTO and USERERR. 


2. Two Levels (error in the called component) 
Assume that a user calls UPAM, which in turn calls PPAM, and PPAM 9 
detects an I/O error. In this case, PPAM returns error code 0227 to UPAM 


in register 15. UPAM alters this code to 0927, places it in the FCB, and 
exits via $GOTO to ERRADR. 
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DMS error codes 


The explanations which refer to the individual error codes appear in a List. 


A List of all error codes with the appropriate explanatory texts can be 
found at the end of this section. 


This List may be printed out, either in full or in part, by means of the 
IDEMS macro: 


IDEMS: 


CALL=Y] 


C,PAM=Y] 


C,CATAL=Y] 


C,ALLOC=yY] 


C,CMDMAC=Y] 


C,CMDNMAC=Y] 


C,UPAM=Y] 


C,ISAM=Y] 


C,SAM=Y] 


C,BTAM=Y] 


C,OPEN=Y] 


C,CLOSE=Y] 


[,P-prefixl 


ALL error codes are generated 
PPAM codes only 

CMS codes only 

ALLOC codes onty 


Only codes for commands with 
corresponding macro 


Only codes for commands 
without corresponding macro *) 


UPAM codes only 

ISAM codes only 

SAM codes only 

BTAM codes only 

OPEN processing codes only 

CLOSE processing codes only 

Appears before all symbolic names in 
DMS messages 


Default value: I 
No Letter generated for P= 


*) FRS messages no Longer have any significance 


In the List of DMS error codes, the codes under 0x90 are missing when x > 9 
(except for SAM). If such a code occurs, its constituent components must be 
analyzed. 
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Note: 
DMS error codes are also contained in the "System Messages” manual. In order 


to Locate a DMS error code in that manual, the Leading zero must be 
replaced by the Letter Dj example: OD33 -> DD33. 


Exception 1: ISA 


The ISAM access method does not conform to these rules. Instead the 
following always applies: 


"Oxyz"="OQAAz', ΖΞ0...Ε 


(z does not take all values within the range O...F.) 


ExampLe: 


If PPAM detects an error after ISAM has been called, 'OAA9* is always entered 
in the FCB. For this error the IDEMS List will contain 


SYSTEM ERROR,HARDWARE 


ISAM produces this message for alt 12 types of error occurring in PPAM. 


Exception 2: OPEN 

Under normal circumstances, the OPEN routine conforms to the formal rules 
regarding coding. However, when opening an ISAM file, errors may occur 
which cannot be explained on the basis of these rules. 


ExampLe: 


If an ISAM fiLe is opened in INPUT mode, the first PAM bLock is read. This 
bLock contains the highest index LeveL. 


A3-6 U805-J-255-5-7600 


DMS error codes 


After an I/U error, the following occurs: 


DOPAM (Privileged PAM) 
"0227" 
DSYSTART CISAM I/O routine) 
"0227" "OAAS* (Conversion) 
DSCOOQOQ (Error routine in ISAM) 
ΣΟΑΑΟ" * ODA9' (Conversion to "OPEN" error) 
DSOISAM (ISAM OPEN error routine) 
DOPEN (OPEN error routine) 
DZGOTO 
OPENER-EXIT 
"0049" > *DDAS* CONVERSION 
AVAILABLE NOT AVAILABLE 
ROUTINE FOR 
USER PROGRAM EJCTERMX ABNORMAL PROGRAM 
TERMINATION 
SYSOUT 


Fig. A.3-2: This error has a different meaning in the IDEMS macro; however, 
here it denotes an I/O error. 


Exception 3: CLOSE 


In order to terminate all outstanding 1/0 operations, the CLOSE routine 
calls the access method appropriate to the file. If an error occurs in this 
access method, an error code y 2 9 is placed in the P1FCB. In this case, 
rule 1 can also be used when y 2 9. 
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Example 1: 


When closing an ISAM file, DCLOSE (CLOSE routine) calls the ISAM-specific 
CLOSE routine. If an error is detected in this, the user will find the 
error 'OEEE' in his P1FCB. 

The error 'OEEE' is not described in the IDEMS List. 


ExampLe 2: 


DCLOSE calls ISAM a second time. Any I/O operations still in progress ere 
terminated. If the termination of such an operation results in an error, the 
user will find the error code OEA9 in the file's PIFCB. Rule 2 would Lead 

to the supposition that the error had been detected by CLOSE -- while it vas 
actually discovered by ISAM. Like the example above, this error is not 
described in the IDEMS List. 


Aids to error anaLysis 
The following actions will assist in the analysis of an error code: 


1. Look up the meaning in the IDEMS List. 


2. Define the error code by means of the HELP command (at the same time 
inserting a D, i.e. /HELP Dxyz). 


3. Ify «9, set x = y and search the IDEMS List again (or via the HELP 
command). 


4. If y 2 9, the error is not included in the IDEMS List, try the same 
method as for y < 9. It may be that the result appears to make no sense, 
in which case analyze the program Logic to determine whether the 
description in the IDEMS List can be accurate or not. 


5. If file management macros are used in a program, register 15 should 
always be tested. If register 15 + 0, the program should be terminated 
or a thorough analysis of register 15 undertaken. 


Error List 


The error List contains the error codes in the IDEMS macro, with an 
expLanation for each code. 

The error codes incLuded in the IDEMS List (IDEMS macro) have a zero in 
their first position instead of the Letter "D". 
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list of error codes: 


IDEMS ALL=Y,P= 
ce dee de ke DMS ERROR MESSAGES VERSION BS2000 V6.0/000 
kkkkkkkkk 

NDQIDEMS 
IDLKG VER=801,ALIGN=C 


*,VERSION 801 
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kk PAM 
DQPAMER EQU  X'Q200*' 
DQTMS EQU  x'0221' TOO MANY SLOTS 
DOHPNIF EQU  x'0222' HALFPAGE NOT IN FILE 
DOCSTER εου x'0223' CSTAT ERROR 
DQRQMER EQU  X'0224' REQM ERROR 
DOILLOP EQU  X*'0225*' ILLEGAL OP 
D@LRCLE EQU χ"ο228" LOGICAL ERROR RETURN CODE 
DQ@IOERR EQU  Xx*'0227' I/O ERROR 
DOINVD  EQU xX*'0228" INVALID DAR INDEX 
© DQINVSL EQU x'0229"' INVALID SLOT ADDR 
DQTCHIO EQU  Xx*'022A* CHAINED I/O ON TAPE 
DODNSER EQU  X"'O022B*' DENSITY ERROR 
DOINVXL EQU χ"ο22ο" INVALID EXTENTLIST 
DQWTACN EQU  X'022D' WAIT AND CONTINGENCY REQUESTED 
DQVLLST EQU  Xx'Q22E' VOLUME LOST 
DQBRSER  EQU x'QO22F' BOURSE ERROR 
DCAIDEMS 
kkk CATALOG 
DKEGEN εου  X*'0300' 
DKINT1 EQU  Xx'0301"' INTERNAL ERROR 01 
DKINT2 EQU  Xx'0302' INTERNAL ERROR 02 
DKINT3 EQU  Xx'0303' INTERNAL ERROR 03 
DKERQO  EQU  Xx*'0330' REQM ERROR 10 
DKEPARM EQU  X'0331' PARAMETER ERROR. 
DKLKERR EQU  X*'0332' LOCK ERROR | 
DKENF EQU — X'0333' ENTRY CANNOT BE FOUND 
DKERQ4 EQU  Xx*'0334' REQM ERROR O4 OR OC 
DKCINT EQU  Xx'033^4* CMS-INTERNAL -ERROR 
DKNONSR EQU  X'0335' NONSHARABLE FILE 
DKEFR1 EQU  X'O033e6' ATTEMPT TO FREE UNLOCKED BLOCK 
DKEFR2 EQU  X'0337*' ILLEGAL ATTEMPT TO FREE BLOCK 
6 DKWFNSP EQU Χ"Ο538" CATALOG FILE HAS 6 OR LESS BLOCKS 
* REMAINING. SYSTEM ADMINISTRATOR 
* MUST ISSUE FILE COMMAND TO 
* ALLOCATE MORE SPACE FOR CATALOG 
* FILE-TSOSCAT. ADDITIONAL SPACE 
κ. NOT RECOGNIZED UNTIL NEXT SESSION. 
DKNSPAC EQU  Xx'0339' CATALOG FILE HAS NO MORE AVAILABLE 
* SPACE. SYSTEM ADMINISTRATOR MUST 
* ISSUE FILE COMMAND TO ALLOCATE 
* MORE SPACE FOR CATALOG FILE-TSOSCAT. 
x ADDITIONAL SPACE NOT RECOGNIZED 
* UNTIL NEXT SESSION. 
DKEFZ2E EQU  X'033A' F1 LABEL UPDATE/DELETE ERROR 
DKENLK EQU  X'O33B' UPDATE CLEAR ERROR: 
*- LOCATE MODE=BLOCK NOT LOCKED 
*- MOVE MODE=CALLER DID NOT READ LAST UPDATE OF ENTRY 
Ὀκεβικ EQU  X'033C' CATALOG FILE AT MAXIMUM SIZE 
DKFCD EQU — X'033D' TSOSCAT OR F1 LABEL BLK DESTROYED 
DKFNEF1 EQU  X*'O3S3E' NEW FILE TO BE CREATED ON PRIVATE 
* VOLUME ALREADY EXISTS IN F1 LABEL 
* AREA 
DKLKSR EQU Χ'Ο55Ε" DKLOCK: FILE SECURED BY ANOTHER TASK 
DALIDEMS 
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κκ ALLOCATOR 
DRNSP EQU X'0441" NO SPACE AVAILABLE - NONE WAS ALLOCATED 
DRDNA EQU X'0442" DEVICE NOT AVAILABLE - $AQIR ERR O4 
DRPLE EQU X'0443" PARAMETER LIST ERROR 
DRBDC EQU X' 0444" CATALOG ENTRY FORMAT ERROR 
DRNOP EQU X'0445' PUBLIC VOLUME NOT ON LINE 
DRCTF EQU X'0446" CATALOG ENTRY IS FULL 
DRNVOL EQU X'0447" OPERATOR CANT MOUNT VOL - SAQIR ERR 14 
DRNMEM EQU X'0448"' INSUFFICIENT MEMORY - $REQM ERR O4 
DRPER EQU X'0449' ALLOCATOR GAVE BAD PARAM TO REQM OR AQIR 
DRINSP EQU X"O44A" SOME SPACE WAS ALLOCATED - EITHER NOT 
* ENOUGH AVAILABLE OR VOLUME NOT ACCESSIBLE 
DRRER EQU X'O44B" CAT-ID NOT FOUND OR PVS NOT AVAILABLE 
DREXSPT EQU X'O44C"' CANNOT READ/FIND USER-ID IN USER-TABLE 
DRINSP2 EQU X'O44D' NO ADDITIONAL SPACE ALLOWED FOR USER 
DREXSPU  EQU X"O44E" DEALLOCATION ERROR 
DRINSP3 EQU X'O44F"' NOT USED 

DMAIDEMS 
kkk COMMANDS WITH MACROS 
DMCMDM EQU X*OS500° 
DMCMSOL EQU X'0501"' REQUESTED CATALOG NOT ACCESSIBLE 
DMCMSO2 EQU X'0502"' REQUESTED CATALOG IN QUIET OR HOLD MODE 
DMCMSO3 EQU ΧΟΡΟΣ) MRSCAT CONTAINS INCORRECT INFORMATION 
DMCMSO4 EQU Χ. 0506) CMS SYSTEMERROR 
DMCMSOS EQU X'0505' MRS COMMUNICATION ERROR 
* 
DMALPDN EQU τοσα FILE-PRIVATE DISK POOL ΙΝΟΟΝΣ. -NO ALLOC. 
DMCMS12 EQU X'0512"' REQUESTED CATALOG NOT FOUND 
DMCATEX  EQU X'0513' CATAL-CMD REJECTED IN SYSTEMEXIT 
DMERAEX  EQU X*0514" ERASE-CMD REJECTED IN SYSTEMEXIT 
DMFILEX EQU κ οσο FILE- CMD REJECTED IN SYSTEMEXIT 
DMALLFS EQU X'0516' ERASE-ALL FILES 7 
DMNOERA  EQU κ ο. ERASE-CMD WITHDRAWN BY CALLER 
DMCOPOV EQU X'0518"' COPY-FILE2 EXISTS. OVERWRITE 7? 
DMNOCOP EQU X'0519"' COPY-CMD WITHDRAWN BY CALLER 
DMF2EXT EQU X" OSIA" COPY-FILE EXISTS ALREADY. CMD TERM. 
DMCMUNO EQU X'O51B' ALL CMDS-USERID NOT IN PVS 
DMCMNAC  EQU X'051C" ALL CMDS-USER HAS NO RIGHT ACCESS 
DMCMPWD  EQU X'051D"' ALL CMDS-LOGON PASSWORD DIFFERENCE 
DMCMPDP EQU X*OS1E°* FILE-PRIVATE DISK POOL INCONSISTENT 
* 
DMCMNSL EQU X'0521"' NO SLOTS 
DMCMHNT  EQU X'0522"' HALF PAGE NOT IN FILE 
DMCMCT4 EQU X'0523' $CSTA-ERROR O4 
DMCMRQ4 EQU X'0524" S$REQM-ERROR O4 
DMCMOP EQU X*O0SRBS' BAD OP-CODE 
DMCMBUF  EQU X'0526' BUFFER PAGE BOUND 
DMCMIO EQU X'0527' I/O ERROR 
DMCMEXT  EQU X'0528' NO EXTENT-LIST 
DMCMBSL  EQU X'0529' SLOT ADDR INVALID 
DMCMCSC EQU X'O052B' $CSTA-ERROR OC 
DMCMRQC EQU X'052C' SREQM-ERROR OC 
DMCMSC1 EQU Χ'ΩΞΖΕν $CSTA-ERROR 10 
* 
DMCMBFN EQU X*'0531"' INVALID PARAM IN CHS-CALL 
DMCMFIL  EQU X'0532"' FILE LOCKED 
DMCMCAT  EQU X'0533"' FILE NOT CATALOGED 
DMCMCR EQU X'0534"' INTERNAL CMS-ERROR 
DMCMNSH EQU X'0535"'" FILE NOT SHAREABLE 
DMCMFTU  EQU X'0536' FRCT-CATALOG ALREADY UNLOCKED 
DMCMFTI EQU ο ΦΕΝΟΤ INVALID 
DMCMF1L EQU X'053A"' F1-LAB UPD ERROR 
DMCMUCE  EQU X'O53B' UPDATE CLEAR ERROR 
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DMCMFMS 
DMCMF1D 
DMCMFEX 
DMCMFSC 
* 
DMCMNSA 
DMCMAAQ 
DMCMPLE 
DMCMCEE 
DMCMPVN 
DMCMCEF 
DMCMA14 
DMCMRO4 
DMCMRAE 
DMCMNOS 
DMCMARQ 
DMCMNUI 
DMCMSNA 
DMERS4F 
* 

* 

DMF CTOF 
DMF VRVC 
DMFMDNG 
DMFAAI 
DMFNFWF 
DMFFFPC 
DMFNDFF 
* 
DMFIMVF 
DMFFPVI 
DMFIVSN 
DMFDNA 
DMF ΥΝΜΕ 
DMFFNIF 
DMFINAU 
* 
DMESOUT 
DMESDU 
DMESNA 
2MESEM 
DMESER 
DMESPRP 
DMTEMP1 
κ 

DMF VWDL 
DMFMPV 
DMFIV 

* 
DMFAPM3 
DMFRQO4 
‘DMFPNPM 
DMFDACD 
DMF AMUB 
DMTMPSF 
DMRLNF 
DMRFO 
DMFRQOC 
DMRIL 
DMRISP 
DMCCPE 
* 


DMFCPE 


EQU 


X'053C' 
X'053D' 
X" OSSE? 
X'053F' 


X'0541"' 
X'0542"' 
X'0543' 
X'0544" 
X'0545"' 
X'0546"' 
X'0547"' 
X'0548"' 
X'0549"' 
X' 054A" 
X'054B' 
X'054C"' 
X'054D' 
X'Q54F' 


X'0550' 
X'0551"' 
X" 0552" 
X'0553"' 
X'0554"' 
X'0555"' 
X'055B' 


X'0557' 
X'0558' 
X'0559* 
X'055A*' 
X'055B' 
X" 055C° 
X'OSSE' 


X'0570' 
X'0571"' 
X'0572* 
X'05735' 
X'0574* 
X'0575"' 
X'0579' 


X'0590' 
X'0591"' 
Χ 0592" 


Χ 0595 
X*0594" 
Χ 0595 
Χ 0596" 
Χ΄ 0597" 
Χ 0598" 
X*'059A' 
X'Q59B' 
X'059c"' 
X'059D' 
X'OS59E' 
X*OS9F* 


X' 05Α1) 


U805-J-Z255-5-7600 


DMS error codes 


CATALOG FILE AT MAX SIZE 

F1 LABEL DESTROYED 

FILE EXISTS ALREADY ON F1 LABEL 
FILE SECURED BY ANOTHER TASK 


NO SPACE AVAILABLE 

DEVICE NOT AVAILABLE 

PARAMETER LIST ERROR 

CE-FORMAT ERROR 

PUBLIC VOLUME NOT ONLINE 

CE AT MAX. SIZE 

OPERATOR CANNOT MOUNT VOLUME 

INSUFFICIENT MEMORY AVAILABLE 

REQM OR AQIR ERROR 

NOT ENOUGH SPACE,SOME WAS ALLOCATED 

CATID NOT FOUND OR PVS NOT AVAILABLE 

FILE-CANNOT READ/FIND USERID IN JOINFILE 

NO ADDITIONAL SPACE ALLOWED FOR USER 

CATAL-UNEXPECTED ERROR WHEN 
ACCESSING JOINFILE 


FILE--TFT ASSOCIATED WITH AN OPEN FILE 
FILE--VSN REPEATED FOR TAPEFILE 
FILE--TOS MOUNT AND DEVICE NOT PRESENT 
FILE--ABS ALLOCATION ILLEGAL 
FILE-IMPORT--NO OR INVALID FILENAME 
FILE--FILE PREVIOUSLY CATALOGED 
FILE--NO OR INVALID DEVICE AND 
STATE=FOREIGN 
FILE--ILLEGAL VSN 
FILE--FOREIGN-PUBLIC VOLUME ILLEGAL 
FILE--ILLEGAL MOUNT PARAMETER 
FILE-IMPORT--DEVICE NOT AVAILABLE 
FILE--1ST PRIV. VOL. OF FILE NOT MOUNTED 
FILE-CATAL--FOREIGN FILE NOT IN VTOC 
FILE--$UID NOT ALLOWED FOR UNCAT FILE 


ERASE--CMD NOT ALLOWED IN INTERACT. MODE 
ERASE--SYSTEMFILE IS ASSIGNED TO *DUMMY 
ERASE--SYSTEMFILE NOT ASS. TO A DMS FILE 
ERASE--SYSTEMFILE IS EMPTY 

ERASE--DMS ERROR OCCURED DURING ERASE 
ERASE--DECLARATIVE PRINT/PUNCH ACTIVE 
CATAL-FILE--INVALID PARAM FOR TEMPFILES 


FILE--VOLUME WITHOUT DEVICE ILLEGAL 

FILE--MOUNT PRIVATE VOLUMES FOR FILE 

FILE-IMPORT--INVALID/TOO MANY/NOT ENOUGH 
VSN'S : 

FILE--ABS MUST BE MULTIPLE OF 3 

FILE-HOLD-REL--INSUFFICIENT MEMORY 

FILE--PUB & NON-PUB MIXED 

FILE--DEVICE TYPE DISAGREES WITH C.E. 

FILE--ABS MUST BE UNIT BOUNDARY 

ALL CMDS--TOO MANY PARAMETERS GIVEN 

REL--LINK NOT FOUND 

REL@--FILE OPEN 

FILE--INVALID REQUEST MEMORY 

REL--INVALID LINK NAME 

REL--INVALID PARAM/PRIVILEGED FUNCTION 

CATAL--COMMAND PARAMETER ERROR 


FILE--COMMAND PARAMETER ERROR 
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DMS error codes 


DMFIDP 
DMFISP 
DMKLERR 
DMCIFP 
DMCISP 
DMOIFP 
DMFAQO8 
DMOISP 
DMEIP 
DMFSNAA 
DMEIP2 
DMFSRLE 
DMFSSE 
DMFNSA 
* 
DMFAQ10 
DMFLK 
DMERNFC 
DMEONRE 
DMFAQ14 
DMORQO4 
DMERQOG 
DMSI1P 
DMSRQO4 
DMSI2P 
DMSISP 
DMSI4P 
DMSISP 
DMORQOC 
DMERQOC 
DMEPWDE 
* 
DMSRQOC 
DMORQ1O 
DMLINKO 
* 
DMELOCK 
DMFMSO4 
DMETNV 
* 


DMEXPDE 
* 
DMERLME 
DMFMSO8 
DMECATO 
DMERAQE 
DMCFN1LE 
DMCFAC 
* 
DMCFN2E 
DMCFNC 
DMCPWDE 
* 
DMCLOCK 
DMCAAQE 
DMCCDER 
* 
DMCRLME 
DMRRLOG 
DMCHNF 
DMCHRFO 
DMCHNVT 
DMFPWDE 
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EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


X'05A2" 
X'05A3" 
X'05A4"' 
X'05AS' 
X'05AB' 
X'05A7' 
X'05A8"' 
X'05AS' 
X'OSAA"' 
X'O5AB' 
X'OSAC"' 
X*OSAD* 
X'OSAE' 
X*OSAF * 


X*OSBO" 
X*O5B1" 
X'05B2' 
X"05B3" 
X'05B4"' 
X'OSB5' 
X'O5B6e' 
ΧΟΡΟΥ: 
X"OSB8" 
X'OSB9' 
X'05BA"' 
X'OSBB' 
X'O05BC"' 
X*OSBD* 
X'OSBE' 
X'OSBF' 


X'O5co"' 
X*"05C1" 
X*OS5C2* 


X'0OSCS3" 
X*O5C4" 
X'05C5' 


X'05Ce' 


X'05C7"' 
χΧχ. 05508" 
X” 0509) 
X'O0OS5CA"' 
X'OSCB' 
X'05CC' 


X*OSCD* 
X" OSCE” 
X'OSCF' 


X" OSDO' 
X'QSD1"' 
X'05Dp2' 


X'OSD3"' 
X'05D4"' 
X'0SD5' 
X*"OS5D6" 
X'05D7"' 
X'05DB8"' 


FILE-IMPORT--INVALID DEVICE PARAMETER 
FILE--INVALID SPACE/DSPACE PARAM 
FILE--DSPACE,DDEVICE,DVOLUME ERROR 
CHNGE--INVALID FIRST PARAMETER 
CHNGE--INVALID SECOND PARAMETER 
COPY--INVALID FIRST PARAMETER 
FILE--DEVICE TYPE NOT AVAILABLE/ILLEGAL 
COPY--INVALID SECOND PARAMETER 
ERASE--INVALID 1ST PARAMETER 
FSTAT-IMPORT--NO AREA ADDRESS 
ERASE--INVALID 2ND PARAMETER 
FSTAT-SRLM1/SRELM ERROR 
FSTAT-SECURITY ERROR 

FSTAT-PASSWORD SPECIFIED,NOT SYS ADM 


FILE--DEVICE NOT AVAILABLE 
FILE--FILE CURRENTLY IN USE 
ERASE--NO FUNCTION CODE SPECIFIED 
ERASE--OWNER NOT REQUESTING ERASE 
FILE--OPERATOR CANNOT MOUNT VOLUME 
COPY-IMPORT--SREQM ERROR 04 
ERASE--S$REQM ERROR O4 
FSTAT--INVALID 1ST PARAMETER 
FSTAT-RDTFT--S$REQM ERROR 04 
FSTAT--INVALID 2ND PARAMETER 
FSTAT--INVALID 3RD PARAMETER 
FSTAT--INVALID 4TH PARAMETER 
FSTAT--INVALID 5TH PARAMETER 
COPY--SREQM ERROR OC 

ERASE--SREQM ERROR OC 
ERASE--PASSWORD ERROR 


FSTAT-SREQM ERROR OC 
COPY--SREQM ERROR 10 
CHNGE|FILE|REL—LINK NAME IN 
PARAMETER LIST=BINARY ZEROS 
ERASE--FILE TO BE ERASED IS LOCKED | 
FILE--$MSG I/O ERROR 
ERASE--SPACE/DATA/DESTROY NOT ALLOWED 
FOR TAPE FILES 
ERASE--EXPIRATION DATE GREATER THAN 
CURRENT DATE 
ERASE--$RLM1/$RELM ERROR 
FILE--$MSG ERROR 
ERASE--CATALOG ONLY FOR PUBLIC VOLUME 
ERASE--SAQIR ERROR 
CATAL--FILENAMEA1 ERROR 
CATAL--STATE-NEW AND FILE CATALED/ 
STATE-UPDATE AND FN2 CATALED 
CATAL--FILENAME2 ERROR 
CATAL--STATE-UPDATE AND FILE NOT CATALED 
CATAL--PASSWORD ERROR 


CATAL--LOCK ERROR 

CATAL-VERIFY- $AQIR ERROR 

CATAL--RETPD SPECIFIED AND NO CR 
DATE IN CE 

CATAL--SRLM1 ERROR 

REL--SRELM ERROR 

CHNGE--LINK NOT FOUND 

CHNGE--FILE IS OPEN 

CHNGE--TOS VOLUME TFT DOES NOT EXIST 

FILE--PASSWORD ERROR 
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DMEEAME 
DMFNORR 
* 
DMOITP 
DMRRLOC 
DMCHNLE 
DMINVFN 
DMFUBLF 
* 
DMALREP 
* 
DMNOTFT 
DMFNINV 
DMCRQO4 
DMEOUT4 
DMERSVL 
DMERNUS 
DMINVGR 
DMEOUTS8 
DMINVTC 
DMMRSCE 
DMCRQOC 
DMEOUTC 
* 
DMCOPFO 
DMCOPF1 
DMCOPEA 
DMCOPEB 
* 
DMCOPEC 
DMCOPED 
DMCOPEE 
DMCOPEF 
* 
DMCOPEG 
DMERSFA 
DMERSFB 
DMERSFC 
DMERSFD 
* 
DMERSFE 
DMERSFF 


kkk 

kkk 
DMCMDNM 
DMPIO 
DMDIP 
DMDLNF 
DMHIFP 
DMHISP 
DMSNSA 
* 


DMERG670 
DMER671 
DMER672 
DMER673 
DMER674 
* 

DMPWROG 
DMPWROC 
DMINVCE 
* 


EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 


X'O5p9' 
X'Q5DA' 


X'O5DB' 
X'OSDC' 
X'O5DD' 
X'OSDE' 
X'OS5DF' 


X” OSEO’ 


4° USE" 
X*OSE2" 
X"OQSE4" 
A* OSES.” 
X"OSE6" 
X'QSEZ' 
X'OSE8' 
X'O5ES' 
X'OSEA' 
X" OSEB” 
X'OSEC' 
X'OSED' 


X'O5FO" 
X” 05F1” 
X'Oosra"' 
X'OSF3"' 


X"OSF4" 
X'OSFS' 
X"OSF6* 
X"OSF7* 


X'OS5F8' 
X" OSFA" 
X'OSFB' 
X'OSFC"' 
X'OSFD' 


X'OsFE' 
X'OSFF' 


DCOIDEMS ,Y,, 
COMMANDS WITH NO MACROS AND VERSION 7 COMMANDS 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 


WITH MACROS 


X" 0600" 
X' 0660" 
X'0561"' 
X" 0662" 
X'0663"' 
X'056^4"' 
X'0668' 


X'0570"' 
X'0671"' 
X'0672" 
X'06573"' 
X'0674"' 


X' 069^" 
X'O69C"' 
X'O59D' 
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DMS error codes 


ERASE--SYSFILE IS NOT PRIMARY 

FILE--1ST SPACE PARAMETER MINUS AND 
FILENAME STARTS WITH $ 

COPY--INVALID THIRD PARAMETER 

REL--$REQM ERROR 

CHNGE--NEW LINK ALREADY EXISTS 

ERASE--INVALID FILENAME 

FILE--ILLEGAL USE OF BLIM/CHKPT PARAMS 


ERASE/FILE--FILE LOCKED DUE TO SPACE 
PROBLEM 
RDTFT--NO TFT WITH LNK/FN 
RDTFT--INVALID FILENAME 
CATAL--S$REQM ERROR 04 
FSTAT-SEOUT ERROR 04 
ERASE--ERROR DURING SEVER 
IMPORT-"NUSERID" RESERVED TO TSOS 
INVALID NAME FOR A DISCFILE 
FSTAT-SEOUT ERROR 08 
FSTAT-INVALID VTOC PARAMETER 
MRS-COMMUNICATION ERROR 
CATAL--SREQM ERROR OC 
FSTAT-SEOUT ERROR OC 


COPY--UNCAT FILE2 BEGINS WITH USERID 
COPY--FILE2 CANNOT BE USED AS OUTPUT 
COPY--*DUMMY FILE OPENED INPUT 
COPY--PASSWORD REQUIRED ISSUE 
PASSWORD COMMAND 
COPY--FILENAMET-FILENAME2 
COPY--$RELM ERROR 
COPY--NON STANDARD BLOCKS INPUT FILE 
ERASE-GEN DOES NOT EXIST,BUT INDEX 
IS UPDATED 
COPY--MSG + DMS RC FROM DMCOPY 
PUBLIC FILE IS NOT IN HOME CATALOG 
IMPORT: USER ID RESERVED TO TSOS 
IMPORT: INVALID USER-ID. 
FILE--SPACE/DSPACE PARAM ABOUT A READ ONLY 
FILE OR BEFORE ITS EXPIRATION DATE 
IMPORT--NO FILE TO IMPORT 
COPY-FILE1 IS A REMOTE FGG 


PASSWORD--INVALID OPERAND 
DROP--INVALID LINKNAME 

DROP--LINK NOT FOUND 

HOLD--INVALID LINKNAME 

HOLD--INVALID SECOND PARAMETER 
SPMGT--SYS ADM NOT REQUESTING FUNCTION 


SPMGT--SYNTAX ERROR IN COMMAND 
SPMGT--INVALID PARAM VALUE IN COMMAND 
SPMGT--PVS NOT AVAILABLE 
SPMGT--$REQM ERROR 

SPMGT--ALLOC REQUEST COUNTER DAMAGE 


PASSWORD--NO MEMORY AVAILABLE 
PASSWORD-- REQM OC 
INVALID CATALOG ENTRY 
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OMS error codes 


IERRD6AOQ0 
CRRD65A2 
i: RRD6A6 
=RRDGAY 
κ 

DMER6B4 
OMER6BS 
AJMER6B8 


DMER6BS 
+ 


* 

ERRD6CO 
ERRD6C1 
ERRD6C2 
ERRDGC3 
ERRD6C4 
ERRD6C5 
ERRD&C5 
ERRD6C7 
ERRD6C8 
ERRD6CS 
ERRD6CA 
ERRD6CB 
ERRD6CC 
ERRD6CD 
ERRD6CE 
ERRD6CF 
* 

ERRDS6DO 
ERRD6BD1L 
ERRD6D2 
ERRD6D3 
ERRD6D4 
ERRD6DS 
ERRD6D6 
ERRD6D7 
ERRD6DS 
ERRD6DS 
* 


ERRDSDA 
* 

ERRD6DB 
ERRD6ODC 
ERRDSDD 
ERRD6DF 
* 


DMVIFN 
* 
DMVNQFN 
DMVLOCK 
DMVNULL 
DMVRQME 
DMVRLME 
DMVMT 
DMVNRP 
* 


DMVISR1 
* 


DMVISMT 
DMVISP1 
* 


DMVISGF 
* 


A3-14 


EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 


EQU 
EQU 


EQU 


X'O6AO' 
X'06A2"' 
X' 05A6"' 
X'O05A9"' 


X'05B^4"' 
X'065B5' 
X'O6B8' 
X"O6B9" 


X” 06C0" 
X*O6C1" 
X'oec2"' 
X'06C3"' 
X*O6C4" 
X*O06C5S* 
X"O6C6* 
X'05C7" 
X'OS5CB" 
X'OB5C9"' 
X'OG6CA"' 
X"O6CB* 
X'O6CC"' 
X'OS5CD' 
X'OGCE' 
X'OS6CF' 


X'OSDO' 
X'O065D1"' 
X'065D2"' 
X'OS5D3"' 
X*O6D4" 
X'O5D5"' 
X'O5D6' 
X" 06D7" 
X'OS5D8"' 
X'O5D9"' 


X" 06DA" 


X*O6DB" 
X'OS6DC"' 
X'O05DD' 
X'OSDF' 


X'O5EO"' 


X'OSGE1"' 
X'O5E2"' 
X'O5ES"' 
X'OS5E^"' 
A*DBES* 
X'OSE6' 
X'O5EbE7"' 


X'OGEB"' 


X'O5ES"' 
X'OBEA"' 


X"O6EB" 


PASS: RFA PROCESSING ERROR 

SECUR: LOCAL/REMOTE RES. MIXED 
CATAL--AUDIT NOT ALLOWED FOR THIS USERID 
CAT/COPY-GEN'S OF FGG ARE MISSING 


ERASE-NO GEN TO BE ERASED 

FILE--CE NOT UPDATED AFTER SYSTEM ERROR 

FSTAT--INVALID OPERAND 

ERASE-FILE-CATAL--ERROR IN SYSTEM EXIT 
BASE MECHANISM 


CATAL- STATE=N & ACCESS=READ 
GEN PARAM. INVALID 

FILE LOCKED BY ANOTHER TASK 
INVALID FGG NAME 

FGG UNDEFINED 

FGG NAME TOO LONG 

ILLEGAL STATE UPDATE 

INCORRECT GEN. NUM. ὦ 
STATE=UPDATE FOR A GEN. UNALLOWED 
ILLEGAL FIRST/GEN/BASE/DISP 
ILLEGAL BASE PARAM. 

AREA SIZE TOO SMALL 

NO FILE CORRESP. TO SUPPORT/STATE 
FGG IS READ ONLY 

INVALID RETENTION PERIOD 

INVALID FILENAME PARAM. 


FOREIGN PRIVATE GEN. DOES NOT EXIST 

FGG SECURED 

INVALID FILE PARAM. 

INCORRECT USE OF FGG 

GENERATION CANNOT BE ERASED 

GROUP/FILE IS READ ONLY 

ERASE OF SOME FILES ON ERROR 

COPY--GROUP CANNOT BE COPIED INTO MEMBER 
GEN. HAVE NOT SAME ATTRIBUTES 
FSTAT-ERROR IN GEN/TYPE/SUPPORT/ 

STATE PARAMETER 

CATAL-FILE--PROHIBITED MIXTURE OF 
GENERATIONS ON ΡΒ. ΟΙΞΚ AND TP/PUB J 
CATAL- STATE=F/VOLUME/DEVICE INVALID 
PASSWORD-PW NOT IN PW-TABLE 

DUP VSN 

ILLEGAL FSEQ/VSEQ/TSET 


VERIFY-INVALID FILENAME(S) 

OR SUPPORT/REPAIR PARAMETER 
VERIFY-FILENAME(S) NOT FULL QUALIFIED 
VERIFY-FILE TO REPAIR MAY NOT BE UNLOCKED 
VERIFY-NO FILE TO REPAIR 
VERIFY-REQM ERROR 
VERIFY-RELM ERROR 
VERIFY-FILE TO REPAIR IS EMPTY 
VERIFY-FILE NOT REPAIRABLE 

(SEE / VERIFY RESTRICTIONS) 
VERIFY-FILENAME2 NOT CATALOGED AND 
FILET IS PRIVATE 
VERIFY"ISAM FILES IS EMPTY 
VERIFY-CANNOT PROCESS ISAM ΕΙι ΕΙ 
REPAIRING TERMINATED 
VERIFY-A GARBAGE FILE WAS CREATED 
WITH THE UNRECOVERABLE DATA BLOCKS 9 
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DMS error codes 


DMVISP2 EQU X*O6EC* VERIFY-ERROR ON FILE2, ISAM 
* REPAIRING TERMINATED 
DMVISG1 EQU X'OSED' VERIFY-UNABLE TO PROCESS THE "GARBAGE FILE" 
DMVISRP  EQU X'OGEE' VERIFY-FILE REPAIRED ON FILE : 
* "REPAIR. <TSN>. <HHMMSS>* 
DMVISA2' EQU X'OSGEF' VERIFY-UNABLE TO ALLOCATE ISAM FILE2 
* REPAIRING TERMINATED 
DMVFUL EQU X'OSFO' VERIFY-DO YOU REALLY WANT TO FORCE UNLOCK? 
DMNOUNL EQU X'übBFT' VERIFY-ONLY HOMELOCKS ARE RESET 
DMVFULR EQU X'O6F2" VERIFY-FORCED UNLOCK REQUESTED BY TSOS 
DMVIUNL  EQU X*O6F3* VERIFY-FILE UNLOCKED 
DMVIREP  EQU X'OG6F^4"' VERIFY-FILE REPAIRED 
DMINVF2 EQU X* OGFS* VERIFY-PARAMETERS RESTRICTED TO SYSADM 
* 
DMERGFS EQU X*OGF6" IMPORT/COPY: INVALID KEYWORD 
DMERSF7 EQU X'OS5FZ7"' IMPORT/COPY: INVALID PARAM 
DMERSF8 EQU X'OGF8"'" DMERASE CATALOG PARAM MISSING 
DMERGF9 EQU X'OSFS9'" DMERASE FN AND VOLUME MISSING 
DMERSFA EQU X'OSBFA"' CATAL“STATE=NEW OR FOREIGN AND 
* FILENAME2 PRESENT 
DMERGFB EQU X'OSGFB' CATAL-EXEC-PW NOT ALLOWED FOR FGG 
DMERSFC EQU X*O6FC* IMPORT-UNEXPECTED I/O ERROR 
DMERSFD EQU X'OS5FD' FILE-INPUT PARAM LIST INVALID 
DMCOOFE EQU X'OB5FE"' RFA BCAM CONNECTION ERR 
DMCOOFF EQU X'OGFF' RFA BCAM CONNECTION INOP 
* : 
DMEROK EQU X'0800' ERASE-FILE ERASED 
DMERERR  EQU X'0801* ERASE-ERASE ERROR 
DMVFREP EQU X'0802"' VERIFY-FILE REPAIRED ON FILE2 
DMVFERR EQU X'0803"' VERIFY-ERROR OCCURED WHILE 
* REPAIRING THE FILE 
DMERRES  EQU X'O806' VERIFY-ERROR ON RESERVE 

NDWIDEMS 

IDLKG VER=831,ALIGN=C 

* VERSION 831 

kkk PTAM 
DWPTAME EQU X'0700"' 
DWRQMER  EQU κ ο 1 REQUEST MEMORY ERROR 
DWINVD EQU X'0772"' INVALID DAR IDENTIFIER 
DWCSTER EQU X'0773"' CSTAT ERROR 
DWNEXST EQU X'0774" WANTED TAPE POSITION DOESN'T EXIST 
DWILLOP EQU X'0775" ILLEGAL OP-CODE 
DWLRCLE EQU X'0776"' LOGICAL ERROR RETURN CODE 
DWIOERR EQU X'0777"' 1/0 ERROR 
DWNAC EQU X'0778"' WAIT/CHECK NOT ALLOWED 
DWVLLST EQU X'0779"'" VOLUME LOST 
DWBRSER EQU X'077A"' BOURSE ERROR 
DWWRE EQU X*'077B' WRITE ERROR 

DUPIDEMS 
* kk NONPRIVILEGED PAM 
DQNPAME  EQU X'0900"' 
DQHFPG EQU Χ"Ω922" HALF PAGE NOT IN FILE 


DQNFCBG  EQU X'09S90' NO FCB ADDRESS GIVEN 


* (OR HIGH ORDER BYTE OF FCB ADDRESS NOT O, 
* OR EXECUTE FORM OF A PAM MACRO OCCURS 

* WITHIN A PARAMETER LIST CHAIN 

DQWTIF EQU Χ 09917 WRITE TO INPUT FILE 

DQNBAG EQU X*Q992" NO BUFFER ADDRESS GIVEN 


* (OR HIGH ORDER BYTE OF BUFFER ADDR ILLEGAL) 


DQBNIAS EQU X"0993" BUFFER NOT IN VIRTUAL MEMORY 
DQFNOAP EQU Χ 0994" FILE NOT OPEN 

DQNILOP  EQU Χ. 0995) ILLEGAL ΟΡ 

DQNCADG EQU X'0996' NO CHECK ADDR GIVEN 
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DQIOEPO 
DQILLEN 
DQIPLTY 
DQIHPN 
* 

* 


DQRTDF 
DQIREQN 
* 
DQIKFLD 
DQKFNVM 
DQICSA 
DQPLNWA 
DQPLNVM 
DQTME 

+ 
DQFINWA 
DQFINVM 
DQNVFCB 


* 
* 

* 

DQNKF MK 
DQEVDUP 
DQSYASC 
* 
DQRQBNF 
DOEVINE 
DQSETMK 
DQNFRQB 
ΡΟΝΡΡΙ 5 
OQNALA 
DQUNNL 
DOLNAL 
DOTNL 
DQIC3A 
DOICGA 
DQUPSFO 
DQUPOFE 
AJQUPOFF 


* 
OSISAME 
DSISRQ1 
OSISRQ2 
DSNULL 
* 
DSSOFT 
DSIO 
DSUSER 
* 
DSSPACE 
DSISPER 
DSBADF1 
* 
DSVALER 
DSNOFND 
DSHARD 
DSPGLOK 
DSSEQ 
DSSPCZR 
DSEOF 
DSDUPKY 


A3-16 


EQU K'"USSr" 
EQU X" 09998" 
EQU X"0999? 
EQU X" 099A" 
EQU X'099B' 
EQU Xx" Q996" 
EQU X'OSSD"' 
EQU X” 099E" 
EQU X*O99F* 
EQU X'OSAQ"' 
EQU X'OSA1"' 
EQU X'09A2" 
EQU X* QSAR" 
EQU X*OSA4* 
EQU X*QSAS° 
EQU Χ'Ο9Α6" 
EQU Χο 
EQU X'OSAS8"' 
EQU X'OSAS"' 
EQU X'09AA"' 
EQU X'OSAB' 
EQU X'OSAC"' 
EQU X' 0980) 
EQU X'OSB1"' 
EQU X'09B2"' 
EQU X'OSBS' 
EQU X'OSB^4"' 
EQU X*Q9B5" 
EQU X*O9B6" 
EQU X*OSFO* 
EQU X'OSFE' 
EQU A: USEF? 
DISIDEMS 
ISAM 

EQU X'OAOOQ'* 
EQU X'OAO1"' 
EQU X'OQAO2"' 
EQU X"OAAO* 
EQU X*OAAL"* 
EQU X*OAA2* 
EQU X'OAA3' 
EQU X'OAA4"' 
EQU X'OAAS' 
EQU X'OAAG' 
EQU X'OAAZ7"' 
EQU X*OAA8* 
EQU X'OAA9"' 
EQU ΧΤΏΑΛΑ" 
EQU X'OAAB' 
EQU X'OAAC' 
EQU X" QAAE" 
EQU X'OAAF' 


I/O ERROR ON PREVIOUS OP 
ILLEGAL LENGTH 
INVALID PAM PARAMETER LIST TYPE 
ILLEGAL HALFPAGE NUMBER 
(HIGH ORDER BYTE OF HP FIELD ILLEGAL OR 
HALFPAGE NUMBER NOT GREATER THAN O) 
READ TO DUMMY FILE 
ILLEGAL REQNO PARAMETER 
(NEGATIVE, O0, OR TOO LARGE) 
ILLEGAL HIGH ORDER BYTE IN KEYFLD PARAM 
KEYFLD NOT IN VIRTUAL MEMORY 
INSUFFICIENT CLASS V WORKSPACE AVAILABLE 
PARAMETER LIST ADDRESS NOT WORD ALIGNED 
PARAMETER LIST NOT IN VIRTUAL MEMORY 
TOO MANY ELEMENTS IN PARAMETER LIST CHAIN 
(OR PARAMETER LIST CHAIN LINKED IN A CIRCLE) 
FCB ADDRESS NOT WORD ALIGNED 
FCB NOT IN VIRTUAL MEMORY 
FCB ADDRESS IN PAM PARAMETER LIST NOT VALID 
(FILE NOT OPENED, FCB HAS BEEN OVER- 
WRITTEN, GIVEN ADDRESS IS NOT THE ADDRESS 
OF AN FCB, ETC.) 
KEY FIELD NOT SPECIFIED & 
SAME EVENT IDENTIFIER FOR TWO OUTSTANDING I/O'S 
IMPOSSIBLE COMBINATION OF SYNCHRONOUS 
AND ASYNCHRONOUS PARAMETERS 
REQUEST BLOCK NOT FOUND 
EVENT IDENTIFIER NOT ENABLED 
MULTIPLE PAGES ON A SETL OPERATION 
NO MORE FREE REQBK AVAILABLE 
DEADLOCK 
NOT ALL REQUESTED LOCKS AVAILABLE 
ATTEMPT TO UNLOCK A PAGE NOT LOCKED 
ATTEMPT TO LOCK A PAGE ALREADY LOCKED 
ATTEMPT TO ACQUIRE TOO MANY LOCKS 
INSUFFICIENT CLASS III WORKSPACE AVAILABLE 
INSUFFICIENT CLASS IV WORKSPACE AVAILABLE 
ILLEGAL PPL CHAIN 
RFA BCAM CONNECTION ER 
RFA BCAM CONNECTION INOP 


MULTIPLE KEYS WISHED 


ISREQ:NO ISAM PAGE LOCK 

ISREQ: ISAM LOCK ON ANOTHER FILE 

NULL ISAM FILE BEING OPENED 

INOUT/EXTEND 

SYSTEM ERROR, SOFTWARE 

SYSTEM ERROR, INPUT/OUTPUT 

USER ERROR, ILLOGICAL USE OF AN 
ACTION MACRO OR ILLEGAL ACTION 

INSUFFICIENT SPACE FOR DATA 
INSUFFICIENT SPACE FOR INDEX 
INVALID P1 FCB ADOR GIVEN TO ISAM 
BY USER ON SVC CALL 

BUFFER POINTER VALIDATION ERROR 

SPECIFIED RECORD COULD NOT BE FOUND 

SYSTEM ERROR, HARDWARE 

PAGE IS LOCKED 

RECORD OUT OF SEQUENCE 

2ND ALLOCATION COUNT =0 

END OF FILE 

DUPLICATE KEY 
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DMS error codes 


DSISOFE EQU X"OAFE’ RFA BCAM CONNECTION ER 

DSISOFF EQU X'OAFF' RFA BCAM CONNECTION INOP 
DSAIDEMS 

kk SAM 

DISAMER EQU X'OBOO' 

DITHS EQU Αα ρου TOO MANY SLOTS 

DIHPNIF EQU X'0B22' HALF PAGE NOT IN FILE 

DICSTO4 EQU X'0B23"' PAM CSTAT ERR 04 

DIRQMO^4 EQU X'OB2^4" PAM REQM ERR O4 

DIILLOP  EQU X'0B25"' PAM ILLEGAL OP 

DIBNOP EQU X'OB26' PAM BUFF CROSSES PAGE 

DIIOERR  EQU X'0B27"' PAM IO ERR 

DINOPDT EQU X'OB28' PAM NO PDT ADDR 

DIINVSL  EQU X"QB29" PAM INVALID SLOT ADDR 

DICSTOC EQU X'OB2B' PAM CSTAT ERR QC 

DIRQMOC  EQU X'OB2C"' PAM RQM ERR OC 

DICST10 EQU X'OB2F' PAM CSTAT ERR 10 

DIWCST4 EQU X'0B73*' PTAM CSTAT ERR 04 

DIWILOP EQU X'0B75"'" PTAM ILLEGAL OP 

DIWBNOP EQU X'0B76"' PTAM BUFF CROSSES PAGE 

DIWIOER EQU X'0B77"' PTAM IO ERR 

DIWCSTC EQU X'OB7B' PTAM CSTAT ERR OC 

DIWCSTF  EQU X*OB7F* PTAM CSTAT ERR 10 

DIBLKCK EQU X*OB8O0" ENSVC147- BLOCK COUNT CHECK FAILS 

DIFAI EQU X*OBBO* FCB ADDRESS INVALID 

DINOEOF EQU X'OBB1"' EOF ADDR OMITTED FROM EXIT LIST 

DINONSP EQU X'OBB2"' NOSPACE OMITTED FROM EXIT LIST 

DISTL1E EQU X'OBB3' SETL CANNOT BE PERFORMED 

DISTL2E EQU X'OBB4"' SETL BUFF NR EXCEEDS FILE LIMITS 

DISTLSE EQU X'OBBS' SETL RCD NR NOT IN BUFFER 

DILLOG1L EQU X'OBB6' ACTION MACRO NOT PERMITTED 

DINWLER  EQU X'OBBZ7' WLERR/ERROPT OMITTED FROM EXIT LIST 

DINEROP  EQU X'OBBS8"' ERRDPT OMITTED FROM EXIT LIST 

DINDATA  EQU X'OBB9' KEY VARIES FROM FLID 

DINTPAM EQU X'OBBA' SAM HAS READ NON-PAM BLOCK 

DIURWLR EQU X'OBBB' USER HAS RECD WR LGTH ERR 

DINBLIM  EQU X'OBBC' EOV BEFORE BLIM CONDITION OCCURED 

DISAO0FE EQU X'OBFE' RFA BCAM CONNECTION ER 

DISAOFF EQU X'OBFF' RFA BCAM CONNECTION INOP 
DBTIDEMS 

wk BTAM 

DPBTAME EQU X'OCOO' EOF FOR *DUMMY FILE 

DPNFCBG EQU X*OC90° NO FCB 

DPWTIF EQU X'OC91"' WRITE TO INPUT FILE 

DPNBAG EQU X'0c92* NO BUFFER ADDRESS GIVEN 

DPBNIAS EQU Χ'ΩςΘ95" BUFFER NOT IN VIRTUAL MEMORY 

DPCSTO4 EQU X'OC94"' CSTAT ERROR O4 

DPILLOP EQU X'OC95" ILLEGAL OP 

DPNCADG EQU X'Oc9e' NO CHECK ADDR GIVEN 

DPIOEPO EQU X'QC97' I/O ERROR ON PREVIOUS OP 

DPIOERR EQU X'OC98"' I/O ERROR 

DPBCPB EQU X'Oc99' BUFFER CROSSES PAGE BOUNDARY 

DPFNO EQU X'OC9A"' FILE NOT OPEN 

DPRTDF EQU X'OC9B' READ TO DUMMY FILE 

DPCSTOC EQU X'OCc9c"' CSTAT OC 

DPCST10 EQU X'OCAO' CSTAT 10 

DPRQMO4 EQU X'OCB^4"' REQM 04 

DPRQMOC EQU X*OCBC* REQM OC 

DPBTOFE EQU X"OCFE’ RFA BCAM CONNECTION ER 

DPBTOFF EQU X'OCFF' RFA BCAM CONNECTION INOP 
DOPIDEMS 


Li£idsiid: OPEN ἀἄΑΛΑΑΑΑΑΑΑΑΑΑΑΑΑΑΛΑΚΑ 
DOPENER  EQU X'ODOO' 
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DNS error codes 


DONOOPN 
DOCKPER 
DOEXERR 
* 


DOILPOS 
* 
DOFCBO 
DOPASSE 
DOE XPDE 
DONVSNM 
DOTSTIN 
DOPARME 
DOBF ORO 
DOAQE 
DOSINOE 
DOLOCKE 
DONOTOP 
DOWRLA 
DOTVINV 
DOWNVSN 
DONDTCE 
DOWRQA 
* 
DOVSNNC 
DONOVL1 
DODAFAL 
DOHDRCT 
DONOHDR 
DOVSNOP 
DOYETOP 
DONODEV 
DOIOBOT 
DODZGOE 
DODZREE 
DORELER 
DOFCBTE 
* 


DOOTEQZ 
* 
DOOTIAM 
DIXTOE1L 
DIXTOE2 
DILRTNE 
DIRPE1 
DIILOGD 
DOBADDY 


DOISRFE 
* 


* 
DOISBER 
DOIORER 
* 


* 
DOISBNE 
* 
* 
DOTVSQF 
DOISPAD 
DOISRRE 
* 


DOOPNSE 
* 


* 
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EQU 
EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 
EQU 


EQU 


EQU 
EQU 


EQU 


EQU 
EQU 
EQU 
EQU 
EQU 


EQU 
EQU 


EQU 


EQU 
EQU 
EQU 


EQU 


X'OD10O" 
X" 0D12”" 
X” 0D15” 


X'OD79' 


X'OD9Q"' 
X'O0D91"' 
X'ODS92' 
Χ 00953" 
X'OD94" 
X*OD95° 
X'O0D96" 
X'ODS97"' 
X'ODS8"' 
X*OD99" 
X'OD9A' 
X'ODSB"' 
X'OD9C" 
X'OD9D' 
X'ODSE"' 
X'ODSF' 


X'ODA1"' 
X'ODA2"' 
X'ODA3"' 
X' 0DA^4" 
X*ODAS* 
X'ODA6G"' 
X'ODAB"' 
X*ODA9* 
X"ODAA* 
X*ODAB* 
X'ODAC' 
X'ODAD"' 


.X' ODAE' 


X*"ODAF * 


X'ODBO' 
X'ODB1"' 
X'ODB2"' 
X'ODB3" 
X*ODB4" 
X'QODBS"' 
X'ODB6' 
X*ODB7* 


X'ODB8"' 
X'ODBS9"' 


X'ODBA' 


X*ODBB* 
X" ODBC” 
X*ODBD* 


X'ODBE' 


OPEN RESTRICTED BY SYSTEM ADMIN. 
ERROR DURING CHECKPOINT 
ERROR DURING RZ-EXIT ROUTINE 


ILLEGAL.TM.COUNTER 


FCB ACTIVE/TFT ACTIVE/TFT TOS 
NONE/INVALID PASSW.FOR PROTECT.FILE 
EXPIRATION DATE NOT SATISFIED 

1ST PRIVATE VSN NOT MOUNTED 

INVALID USE OF TSET OR FSEQ 

IOAREA ERROR 

OUTPUT/OUTIN SPEC. FOR FOREIGN TAPEF. 
$AQIR ERROR 

SINOUT:BUT FILE NOT: TAPE/BTAM/FOREIGN 
FILE IS LOCKED 

OPEN INPUT, BUT FILE IS EMPTY 

$REQM OR GRELM ERROR 

TVSN OR VSEQ SPEC. WITH DISK FILE 

NO VSN (OR NO EXTENTS) IN CAT ENTRY 
DEVICE TYPE NOT PRESENT IN CATALOG 
FCB ADDRESS INVALID 


VSN DON'T MATCH 

VOL1 NOT FOUND 

WRONG OVERWRITE ACCESS 

HDR1 OR HDR3 CONTENT (TO CONCOLE) 
DISPLAY WRONG FILE IDENT. TO CONSOLE 
VSEQ AND OPEN NOT COMPATIBLE 
VOLUME CURRENTLY OPEN 

NO FREE DEVICE EXISTS FOR MOUNTING 
STATIC INOUT WITH BOT 

DZGOTO ENTRANCE INVALID 

DZRET ENTRANCE INVALID 

REL MACRO ERROR 

FCBTYPE IN COMPLETED P1 FCB 
INCONSISTENT WITH FCBTYPE IN CE 
OPEN TYPE IN P1 FCB EQUAL TO ZERO 


OPENTYPE INVALID FOR ACCESS-METHOD 
INVALID SPACE (<BLKSIZE) FOR SAM FILE 
NO ALLOCATION POSSIBLE (SAM/ALLOC. ) 
UNABLE TO LOCATE LOGICAL ROUTINE 
CANNOT PROCESS REV IPT FILE 

NSTD BLOCKS SPEC ON RA DEV 
FCBTYPE=ISAM AND FILE RESIDES ON TAPE 
FCBTYPE=ISAM AND RECFORM=U/RECFORM=F 
AND RECSIZE=0 IN FCB/RECFORM IN FCB 
NOT EQUAL TO RECFORM IN CATALOG ENTRY 
BLK TYPE NOT STD OR BLKSIZE>(STD,16) 
ISAM/SAM IOREG NOT BETWEEN 2-12 OR 
SAM VARBLD OR RECSIZE REG NOT 

BETWEEN 2-13 

FCBTYPE=ISAM AND BUFFER SIZE IN P1 
FCB NOT EQUAL TO BUFFER SIZE IN ISAM 
LABEL AREA 

VOL SEQ # ERROR 

PAD VALUE INVALID FOR BLKS/RECS PARAM 
FCBTYPE-ISAM AND RECSIZE IN P1 FCB 

» RECSIZE IN ISAM LABEL 

SYSTEM ERROR-CONDITION OCCURRED IN 
DOPEN WHICH IS POSSIBLE ONLY IF 
SYSTEM IS NOT FUNCTIONING PROPERLY 
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DOWVTFT 
* 


DOISKK 
* 


JONULLI 
* 
OIOPER1 
JOF2BIG 
DIOPER2 
DOFDIFF 
* 
DOFRSE 
* 
DOLGTHO 
DOOFRSM 
DOCFNT 
DOCBCS 
DOIRCVS 
DOIBCVS 
DOANSOC 
DOUNLFD 
DOTPLBR 
* 
DOPCRL 
DOPNCER 
DOILRES 
ERRDDD3 
DOBTMNA 
DORVUIN 
DOWVMOU 
DOACCFA 
DOHDRNO 
DOUSLER 
DOPSWDI 
DOFSQIN 
DOF SQNF 
DOTMFNS 
DOWMNT 
DOWRFSQ 
* 


DOFUBLO 
DOEOVEF 
DOPREMT 
DOBKFAL 
DOVOLOC 
DOEOTMF 
DOEORCF 
DOEO2TF 
DOEOBCI 
DOOFSEQ 
* 


DOQTMRQ 
DOQGRQER 
DOQTSER 
* 


DOQNPSU 
DOQTPSU 
DONOHME 
DOWLABI 
DOWLABO 
DIMVDEV 
DIODFS 

DINDINC 


EQU 


EQU 


EQU 
EQU 


X'ODBF' 
X' ODCO' 
X'ODC1"' 


X'ODC2"' 
X'ODC3"' 
X'ODC4" 
X'ODC5' 


X'ODC6e' 


X'ODCZ7' 
X'ODC8' 
X'ODCS9' 
X'ODCA"' 
X'ODCB' 
X'ODCC*' 
X'ODCD' 
X'ODCE"' 
X'ODCF' 


X" ODDO" 
X' ODD1"' 
X'ODD2"' 
X'ODD3"' 
X' ODD4* 
X'ODDS' 
X'ODD6' 
X'QDD7*' 
X'ODD8"' 
X'ODD9"' 
X' ODDA' 
X*ODDB* 
X*ODDC* 
X' ODDD' 
X'ODDE"' 
X'ODDF' 


X'ODEO' 
X'ODE2"' 
X'ODES"' 
X* QDE6* 
X'ODE8"' 
X'ODES"' 
X" ODEA" 
X'ODEB' 
X'ODEC"' 
X" ODED” 


X'ODFO"' 
X'ODF1"' 
X'ODF2"' 


X'ODF3' 
X'ODF4"' 
X'ODFS"' 
X*ODF6* 
X*ODF7* 
X*"ODF8" 
X'ODFS"' 
X'ODFA"' 
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DMS error codes 


#VSNS IN TFT NOT EQUAL #VSNS IN CE 


ISAM WITH RECFORM-F AND KEYLEN+ 
(VALLEN*LOGLEN) + KEYPOS > RECSIZE 
FCBTYPE-ISAM,OPEN TYPE=INPUT AND 
FILE TO BE OPENED IS NULL 
RECFORM/RECSIZE NULL OR IN ERROR 
KEYLEN*VALLEN*LOGLEN»255 

BLKSIZE CANNOT BE CHANGED ON PAM 
ISAM: OPEN-INOUT, VALLEN/LOGLEN/VAL- 
PROP NOT EQUAL TO CATALOG VALUE 
RECON/RESET/OPT BITS SET FOR OUTIN/ 
OUTPUT 

ISAM OPEN:  KEYLEN OR KEYPOS IS ZERO 
PAM-MOVE MODE ERROR IN FRS 

CODED FILE NOT A TAPE FILE 

ILLEGAL BLKSZ ON CODED TP 

ILLEGAL RECSZ ON CODED SAM V TP 
ILLEGAL BLKSZ ON CODED SAM V TP 
ACTRTAB) NOT SPEC ON OWNCODE TP 

FILE CODE INCOMPATIBLE WITH TAPECODE 
UNDEFINED LABEL FIELD 


UNABLE TO OPEN DUE TO SPEC CAT LOCKS 
FILE NOT CLOSED-USE VERIFY TO REPAIR 
ILLEGALE RESPONSE TO MSG 'DDE4"' 
ATTEMPT TO OPEN A GROUP INDEX (FGG 
ILLEGAL USE OF BTAM / PAM i 
RECFORM=U OR V AND LABTYP NOT OK 
WRONG FILE SET IDENTIFICATION 

ACCESS FAILURE 

NO STD LABEL FOUND 

USER REPORTS ERROR FOR NSTD LABEL 
PASSWORD DIFFERENT 

INVALID FILE SEQUENCE NUMBER 

ILLEGAL BLP PARAM 

TM DETECTED BUT NOT SPECIFIED 

MOUNT MSG (WARNING) 

WRONG FSEQ 


ILLEGAL USE OF BLIM PARAM 

EOV ASSUMED AS EOF 

PRE MOUNT 

BLOCK COUNT FAILURE 

VOL SWITCH OCCURS (SAM) 

EOF /EOV NOT FOUND TM FOUND 

EOF /EOV NOT FOUND RECORD FOUND 
EOF /EOV NOT FOUND : 2 TM FOUND 
EOF /EOV : BLOCK COUNT INCORRECT 
INV FSEQ# AT OPEN 


TOO MANY PAM REQUESTS 

NOT ENOUGH CLASS 4 OR 5 MEMORY AVAIL. 
TASK SYNCHRONISATION COULDN'T 
ACQUIRE THE REQUESTED LOCKS 

ATTEMPT TO OPEN A NON-PAM FILE PAM SU 
ATTEMPT TO OPEN A TAPE FILE PAM SU 
FILE NOT ON HOME PUBLIC VOLUME 

WRONG LABEL FORMAT OPEN INPUT 

WRONG LABEL FORMAT OPEN OUTPUT 
MOUNTED VSN NOT = EXPECTED VSN 
INVALID BUFOFF 

WRONG STD LABEL VERSION USED (DIN) 
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DMS error codes 


DONVOLU 
DOILVSN 
DOBYPAS 
DOACFOR 
DOIGNNA 


x oe e v x x x Xx 
* 


DCLOSER 
DCLEOVX 
DCLEOVER 
DCLIOERR 
DCLFCBO 
DCLCMSE 
DCLVSNM 
DCWRLO^4 
DCPCIOE 
* 
DCLWPOS 
* 
PCLERROR 
DILEFCB 
DCLRLA 
DCWRLOC 
DCLRQA 
DCLFEOV 
DCVREV 
DCVNOMT 
DCLISERR 
DCOCOFE 
DCOCOFF 
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EQU X'ODFB' 
EQU X'ODFC' 
EQU X'ODFD' 
EQU X'ODFE"' 
EQU X'ODFF' 
DCLIDEMS 
CLOSE *¥KKKKKKKKKX 
EQU X'OEOQO' 
EQU X” 0E10" 
EQU X'QOE15' 
EQU X'OE77' 
EQU X*OESO0* 
EQU X'OE91" 
EQU X'OE93' 
EQU X'OE9^4" 
EQU X'OE9S"' 
EQU X*OES96" 
EQU Χ'ΟΕ98" 
EQU X'OES9"' 
EQU X'OE9A"' 
EQU X'OE9C"' 
EQU X'OESF' 
EQU X” OEEO” 
EQU X*OEEL* 
EQU X'OEE2" 
EQU X'OEEE"' 
EQU X *OüEFE* 
EQU X'OEFF"' 


"ACKNOWLEDGE VSN ε.. (TO CONSOLE) 


ILLEGAL VSN 

BYPASS FUNCTION CALLED 
ACCESS FORBIDDEN 
IGNORE NOT ALLOWED 


EOV RESTRICTED BY RZEXIT-ROUTINE 
EOV: ERROR IN RZEXIT ROUTINE 
CLOSE I/O ERROR 

INACTIVE FCB 

CATAL ERROR 

INCORR VOLUME MOUNTED 

RELM ERROR 04 

1/0 ERROR(S) WHILE WAITING ONE 
OR MORE UNWAITED I/O(S) 

CANNOT WRITE EOF LABELS, LAST OP 
NOT WRITE (TAPE POSITION !) 
ERROR CODE PSEUDO CLOSE 
INVALID FCB ADDRESS 

RELM ERROR 

RELM ERROR OC 

REQM ERROR 

DOCTRLP- EOF AT FEOV HANDLING 
DOCTRLP- OPEN-TYPE-REVERSE 
DOCTRLP- CANNOT MOUNT TAPE 
ISAM-CLOSE-ERROR 

RFA BCAM CONNECTION ER 

RFA BCAM CONNECTION INOP 
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Sense bytes 


A-4 SIGNIFICANCE OF THE SENSE BYTES FOR DIFFERENT DEVICES 


The symbols x and O in column 1 have the following significance: 


x If the condition is satisfied, bits 2’ and 25 in byte 35 of the CCB are 
set to 1 by the Control Systen. 


ο If the condition is satisfied, bits 27 and 2° in byte 35 of the CCB are 
set to 1 by the Control System. i 
Card reader - sense byte 1 


27 Read error 
25 Service request not honored 


24 Invalid punch code 
Hopper empty 


XOOOXOXxxXx 
N 
E 


2° IlLLegal operation 
Card punch - sense byte 1 


27 Punch compare error 
26 Punch memory parity error 


- 4 Transmission parity error 


ΧΌΟΟΧΟΧΧ 
Ν 
m 


2 ILLegaL operation 
Printer - sense byte 1 


27 ChanneL 12 punched 
g” Channel 9 punched 


24 Print Line incompLete (243) or parity error (4247) 


xXOOOxOXX 
N 
e 


20 Illegal operation 


Magnetic tape - sense byte 1 


2* Parity error 

2° Service request not honored 

25 Data bLock greater than count 

24 Transmission parity error 

Previous block Less than count 

2? BOT/EOT marker 

p Tape mark 

20 ILLegal operation, invalid control byte, 
or missing write-enabLe ring 


ΧΟΟΧΧΟΧΧ 
N 
m 
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Sense bytes 


Magnetic disk - sense byte 1 


Read error 

Service request not honored 
Seek check 

Transmission parity error 
Track check 

Automatic head switching error 
End of file 

Illegal operation 


Magnetic disk - sense byte 2 


A4=2 


Count fields read error 


Overflow incompLlete 

Missing start-of-block marker 
File protect 

Not found 

Invalid command sequence 

End of cylinder 

End of track 
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ShareabLe private disk 


R.5 SHRRERBLE PRIVRTE DISK 


A compLete description of this function can be found in the "MSCF 
Multiprocessor System" manual. 


The shareable private disk (SPD) function permits controlled access by up to 
4 different processors to one disk device on which a private disk is 
mounted. Access is accomplished via direct hardware paths. 


The Data Management System of the MRS coordinates access to the shareable 
disk devices and synchronizes access to the data on the volumes mounted on 
these disks. Every file on a shareable disk may be accessed at any time by 1 
System in write mode or by up to 4 systems in read mode. From a single 
system, files can also be processed in shared update mode. User programs 
need not be specially prepared for this function. The fact that files that 
are to be accessed reside on shareable files is hidden to the user. No 
special measures need be taken by programs running in different processors 
and requiring simultaneous access to the same file. Files stored on 
shareable disks can be cataloged in one or more or all catalogs of the 
accessing processor. A disk device is considered shareable if it 


e is connected to more than one processor (i.e. there are at Least 2 
access paths via which the disk device may be accessed), and 


e was defined as shareable at system generation time. 


The concept "shareabLe", as defined here, is a feature of the disk device 
and should not be mixed up with the "shareabLe" feature associated with 
files or volumes. This disk device feature is entirely defined by the 
existing hardvare configuration and the system generation. 


A shareable disk device Loses its shareability only if it was defined as 
"unshareabLe" during a new system generation and/or reconfiguration of the 
hardware. Dynamic modification of this feature is not possible. | 


A volume becomes shareable when it is mounted in a shareable disk device. 
The shareability feature can be used only in conjunction with private 
voLumes. 


Hotes on SPD operation 


- It is possible for 1, 2, 3 or 4 processors to access one shareable disk, 
and each of these disks may in turn access other shareable disks. 


Disks mounted on shareable disk devices, as well as files on these 
disks, should only be those which must actually be accessed simultan- 
eousLy from several processors. | 


- A public disk can be mounted in a shareable device but it can be 
referenced only by its owner (operating system). If it is referenced. by 
more than one processor, the results are unpredictable. 


- If a user without remote catalog access (RCA) wants to access a file 
that vas generated by a different processor, he must define this five to 
his own system (TSOSCAT) beforehand by means of a FILE command or macro. 
This is not necessary when the RCA function is used. 
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ShareabLe private disk 


- To minimize the runtime of jobs working with SPD, the following 
considerations should be borne in mind: 


- Primary and secondary allocation in the FILE command should meet 
the expected file size requirements. 


- Catalog entries for SPD files which are continually accessed by more 
than one processor should be kept in all catalogs of the accessing 
systems. This avoids additional time requirements for communication 
(data transmission). 


- The operand VTOC=YES/NO in the FSTATUS command/macro permits output of 


the VTOC catalog entries of private disks to be initiated rather than 
output of the TSOSCAT entries (see the FSTATUS command). 
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Device support 


A-G MEANS OF SUPPORTING DEVICES NOT LOGICALLY SUPPORTED BY BS2000 


TOS (tape operating system) runtime parameters 


The following TOS runtime parameters are supported by the BS2000 command 
Language. The commands are applicable to files processed by TOS FCP 
(File Control Processor) or physical I/O (EXCP). 


Note: 


Commands must contain a slash in column 1 and cannot contain a slash in 
column 2. (In TOS, both columns 1 and 2 have to contain slashes. ) 
Continuation cards must contain a slash in column 1, and the data must begin 
in column 2 (not column 16 as in TOS). Othervise, the command format under 
an operating system with virtual addressing is identical to that required 

by TOS. 


TOS runtime Function 


parameters 

CHANGE Changes the file Link name in a Task File TabLe entry. 

FILE Replaces TOS ASSGN and allows the TOS user to assign private 
devices for his use. 

HOLD | PLaces an entry in the Task File TabLe in the HOLD status. 

CHANGE 


The CHANGE command changes the file Link name or the symbolic device name 
in a Task File Table entry. ALL other values in this TFT entry remain 
unaltered. 


Operation Operands 
CHANGE Link2 
Clinkil, 
symdev 
Link1 This operand specifies the file Link name (1 to 8 bytes). 


If this operand is omitted, the first TFT entry with the 
Link name C'........' is processed. 


Link2 This operand specifies a new file Link name which is to 
replace the previous Link name. 


symdev This operand specifies a new symbolic TOS device name. It 


is provided for reasons of compatibility and is defined 
with a device-oriented, non-standard BS2000 FILE command. 
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Device support 


FILE CASSGN) 


The TOS FILE command repLaces the TOS runtime parameter ASSGN. The TOS format 
of the FILE command is defined below and conforms to TOS command syntax. 


Operation 


FILE 


SYMDEV= 


LINK= 
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Operands 


SYMDEV-sdnl ,LINK-symbou]l 


D5881 
D3455 
D5882 
D3465 
D3468 


L ,DEVICE- J0,MOUNT=mnemonicl] 


This operand specifies that this is a TOS FILE command. 


This operand contains the symbolic device name (sdn) 
required by TOS; maximum Length: 6 characters. 


Note: 
This macro will no Longer be supported after BS2000 V8.O. 


This operand specifies the file Link name. 

Although TOS programs do not make use of this operand, it 
can still be used with other commands (e.g. HOLD, RELEASE). 
If the operand is omitted, a Link name consisting of blanks 
(X"40") is generated. 

If a FILE command has the same Link name as a previous FILE 
command, the new command replaces the old definition. 


Processing takes place in the following sequence: 


FILE command 1 FILE WLINK=X, SYMDEV=ABC 
RELEASE.X,KEEP 
FILE command 2 FILE.LINK-X, SYMDEV-XYZ 


Any private devices associated vith FILE command 1 are 
returned to the job, not to the system. This permits reuse 
of these private devices vithin the job. The devices 
associated vith FILE command 1 are not associated in any vay 
with FILE command 2; they are merely returned to the job. 


U805-J-Z55-5-7600 


DEVICE= 
=D3455 
-D5881 
-D3465 
-D5882 
-D3468 
-D3470 
-D3475 


-D3480 


C -D348E 


© MOUNT= 


Device support 
This operand specifies the device type. 


3455 Disk Storage Unit 


3465 Disk Storage Unit 


3468 Disk Storage Unit 

3470 Fixed-Disk Storage Unit 

3475 Fixed-Disk Storage Unit 

3480 Fixed-Disk Storage Unit 

348E Fixed-Disk Storage Unit 

9-track tape with data conversion 

9-track tape vith maximum recording density 

9-track GCR (group coded recording) 

9-track NRZ (no return to zero) 

9-track PE (phase encoded) 

This operand specifies the system work tape. The system 
requests 9-track system work tapes, previously specified by 


the operator (via the SETUP command). 


If no tape is available, this operand is equivalent to the 
TAPE operand. 


Default value: 
If no operand is specified, TAPE is assumed. 


This operand specifies the installation name of a particular 
device as a 2-character mnemonic. This allows the user 

to specify a preference for a specified device. If this 
operand is specified, the DEVICE operand is ignored. 


Default value: 


The system selects an appropriate device according to the 
device type specified in the DEVICE operand. 


Note: 


This macro will no Longer be supported after BS2000 
Version 8.0. 
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Device support 
HOLD 


The HOLD command places an entry in the Task File Table (TFT) in the HOLD 
status. This serves to defer a subsequent RELEASE command (or REL macro) 

for this TFT entry until a DROP command with the relevant file Link name 

is issued. 


Operation Operands 
HOLD Link 
[{Link,TOS}] 
TOS 
Link This operand specifies the file Link name of a TFT entry to 


be placed in the HOLD status. If no entry with this name 
existed previously, a new TFT entry is created for this 
Link name. Further entries can be made in this TFT entry 
by means of a subsequent FILE command. If "Link" is not 
specified, the first TFT entry vith the Link name 
C'Looeeess' is processed. 


TOS This operand specifies that the TFT entry in question is 
for a TOS file, a file type which exists for reasons of 
compatibility. It is created with a non-standard FILE 
command. | | 
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Device support 
TOS macros in the DMS 


The following macros, related to file processing and device management, are 
available to DMS programs. They may be used for class I programs only. FCB 
macros valid for TOS may also be used for class I programs, but they are not 
discussed here. 


TOS Function 
macro 
ASSGN allows dynamic device assignment for TOS programs. 
CCB allows physical Level I/O specifications for a CCB. 
CCBD generates a DSECT for the CCB. 
Doo erc ton RESE c TREE NN Ck bY See WAR A EE εκ ο MG ο. 


© CHNGE changes the file Link name. 


DDEV allows a program to release a specified device. 


EXCP initiates (or queues) a user's I/O channel program. 


EXCPW same as EXCP except that the user is pended until his channet 
program has been compLeted. 


QUIET places the calling program in a wait state until its I/O 
activity has been completed. 


WALT places the job in a wait state until the 1/0 operation defined by 
the CCB has been compLeted. 


Dynamic device assignment (type O) 


C Operation Operands 


ASSGN ccbaddr 

ccbaddr This operand specifies the address of the CCB containing 
the symbolic device name of the device to be assigned 
(reLexp). 

Note: 


This macro will no Longer be supported after BS2000 Version 8.0. 
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Device support 


CCB Command Control Block (type 0Ο) 


Operation Operands 

CCB symdev,ccw,flags,device-type 

symdev This operand specifies the symbolic name of the device with 
which the CCB is associated (symbol). 


ccw This operand specifies the address of the first CCW to be 
referenced in this CCB (reLexp). 


Note: 
If data chaining is employed, the restrictions Laid down in 
the relevant peripheral control descriptions must be 9 
observed. 
flags This operand specifies the user flags (absexp). 


Significance of the flags: 


X'20' Skip device error handling 

X'10' Error is accepted 

X'04" Suppress device error handling messages 

X'02' Card punch handling/SDLDR already defined 
device-type This operand specifies the device type (absexp). 
Note: 


This macro will no Longer be supported after BS2000 Version 8.0. 
CCBD DSECT for CCB 


Operation Operands 


n 
CCBD Di bs ] 
* 


D This operand is mandatory and specifies that a DSECT is to 
be generated. 


n This operand is optional; any alphabetic character can be 
specified for "n". It serves to specify a freely selectable 
character prefix to be Linked to all names in the DSECT. 


DefauLt value: I 


* This entry specifies that no prefix is to be used. 
Note: 
This macro will no Longer be supported after BS2000 Version 8.0. Φ 
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Device support 
CHNGE - Modify TFT entry (type S) 


The CHNGE macro changes the file Link name or symbolic device name of a 
File Control Block. ALL other TFT entries remain unaltered. 


Operation Operands 


CHNGE Link2 | 


tina | 
symdev 


For a description of the operands, see the CHANGE command. 


DDEV - DeaLLocate device (type 0) 


Operation Operands 


DDEV sdn 

sdn This operand specifies the 6-byte symboLic device name of 
the device to be released. 

Note: 


This macro will no Longer be supported after BS2000 Version 8.0. 


If a TOS FILE has pLaced the device (symbolic device name) in the HOLD 
status, the device is not deallocated. It is deallocated only after a DROP 
command has been issued. 


EXCP - Execute channel program (type 0) 


The EXCP macro performs the same functions as EXCPW, except that control is 
returned to the user after the channel program has been initiated or queued. 


Operation Operands 


EXCP ccb 

ccb This operand specifies the name of the CCB which indicates 
the I/O operation to be initiated (relexp). 

Note: 


This macro will no Longer be supported after BS2000 Version 8.0. 
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Device support 


EXCPH - Execute channel program and wait (type 0) 


The function of the EXCPW macro is to initiate (or queue) the user's I/O 
channel program as specified by the CCW address in the CCB. The user is then 
placed in the wait state until the channel program has been completed. 


Operation Operands 


EXCPW ccb 
ccb This operand specifies the name of the CCB which indicates 
the I/O operation to be initiated (relexp). 
Note: 
This macro will no Longer be supported after BS2000 Version 8.0. 9 


QUIET - Wait for completion of all I/O operations (type 0) 


This macro suspends the calling program until all input/output activities 
have been terminated. 


- 


Operation Operands 


QUIET 

Hote: 

This macro will no Longer be supported after BS2000 Version 8.0. 

HAIT - Hait (type O) J 


This macro is used to place the task in the wait state until all I/O 
activities have been completed. 


Operation Operands 


WALT ccb 

ccb This operand specifies the name of the CCB associated with 
the device on which οἷς aia of I/O activities is 
awaited (relexp). 

Note: 


This macro will no Longer be supported after BS2000 Version 8.0. 
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A-7 DEVICE TYPE CODES 


Family Device 
code type code 


O0 
01 


02 


10 


pp 
RN 


pa 
D> 


20 


N 
þa 


30 
40 
50 


60 


6E 


70 71-7F 
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TOS 
code 


Device type codes 


Devices 


Operator consoLes 

Operator consoles in Systems 7.500, 7.700: 
3020, 3021, 3023 Central Operator Console 
3020-10, 3021-10, 3023-10 SubconsoLe 

3030, 3033-01 Consove Printer 

(optional hardcopy device) 

Operator consoLes in Systems 7.500, 7.700: 
3024, 3026 Central Operator Console 

3024-10, 3025-10, 3026-10, 3026-20 SubconsoLe 
3027-11, 3027-21 Operator Consoles 


Card readers 

237 Card Reader 

4235, 4239-10, 3150-01, 4239-20, 
3150-02, 4239-30, 3150-03 Card Reader 
F617D Card Reader 


Printers 

4245, 4247, 243-10, 243-20, 243-30, 243-31, 
4241-52, 3340-01, 4241-54, 3340-02 Printer 
(132 characters) 

4242-92, 3340-03, 4242-94, 3340-04, 

243-40, 243-41 Printer (160 characters) 
3341, 3342, 3343 Printer 

3352 Laser Printer 

3333, 3336 Printer 

3337-51, -52, 71, 3338-51, 52 Printer 


Card punches 

234 Card Punch 

236 Card Punch 

4238, 3160 Card Punch 


Paper tape devices 
Paper tape reader 
Paper tape punch 
Document reader 


HisceLLaneous devices 

3065 Switch 

TRANSDATA 8170 CLuster Controller (Local) 
PLotter 


TeLeprocessing 

968x Front-End Processor 
968x Front-End Processor 
968x Front-End Processor 

627 Data Exchange Controller 


Physically supported devices 
Plotter, document reader, graphic terminal, etc. 
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Device type codes 


Fami 
code 


A7-2 


Ly 


90 


AQ 


BO 


EO 


Device 
type code 


FA 


Devices 


Floppy disk I/O units 

3170 Floppy Disk I/O Unit 

30243, 30244, 30230, 30263 Floppy Disk 1/0 Unit 
3171 Floppy Disk 1/0 Unit 


Disk storage units 

3470 Fixed-Disk Storage Unit (not with 
4004/151), 3472 Fixed-Disk Storage Unit 
3454, 3455 Disk Storage Unit 

3464, 3465 Disk Storage Unit 

3468 Disk Storage Unit 

3475 Fixed-Disk Storage Unit 

3480 Fixed-Disk Storage Unit 

348E Fixed-Disk Storage Unit 


Magnetic tape devices, 9-track, unimodaL 

432, 442, 4443, 4446 Magnetic Tape Device, NRZ, 
800 bpi 

451, 453; 46620, 3570, 3571, 3530, 3531 Magnetic 
Tape Device, PE, 1600 bpi 

3557, 3559 Magnetic Tape Device, GCR, 6250 bpi 


Magnetic tape devices, 9-track, bimodal 

450, 3550, 454, 3554, 4453, 3540, 3521, 3523 
Magnetic Tape Device, NRZ/PE, 800/1600 bpi 
3557.4 39559, 3525, 25268, 3513, 3516 

Magnetic Tape Device, PE/GCR, 1600/6250 bpi 
3518, 3528 Streaming Tapes 
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GLOSSARY 


The following terms are used throughout this publication and are defined 
here for the convenience of the reader. The majority of these terms are 
also defined where they first appear in the text. 


access method 

A conventional data management technique that defines to the user the 
organization of data and the method of data transfer between an input/ 
output device and the main memory of the system. Examples of DMS access 
methods are ISAM (Indexed Sequential Access Method) or UPAM (User Primary 
Access Method. 


alphanumeric 
Letters A through Z and numerals 0 through 9. 


batch job, non-interactive job 
A job started with the aid of ENTER. 


block 
The unit of transfer to or from an I/O device. For exampLe, the data between 
two interbLock gaps on magnetic tape is a bLock. 


buffer 
A contiguous area of memory. A portion of main memory from which data is 
read or into vhich it is vritten. 


catid 
Catalog ID of a pubset; cf. PVSID. 


cLass I program 

Programs that are restricted to the physical main memory addressing 

capacity of the system. These programs must reside in main memory throughout 
their execution, and require that main memory be assigned to them con- 
tiguousLy. 


cLass II program 

Programs that do not require contiguous main memory for execution and 
reside in the system's virtual memory. These programs are broken up into 
pages (4096 bytes), use the virtual addressing facility of the system, and 
are normally paged between the paging memory and main memory during their 
execution. 


class 1 memory 

That portion of virtual memory that is occupied by those modules of the 
Executive which are resident in main memorye ALL class 1 pages are marked 
privileged and non-pageabLle. No paging memory image exists and these pages 
are resident in main memory throughout the session. 


class 5 memory 
That part of the user's virtual memory containing the pageable areas 
required for a user job that are allocated dynamically by the Executive. 


class 6 memory 


That part of the user's virtual memory containing the user programs that 
are allocated dynamically by the Executive. 
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Command Control Block (CCB) 

An area in a user program in which data is passed between the user and the 
input/output device accessed by the program. The CCB is used for physical 
Level I/O programming. 


CSECT (control section) 

A part of a program that can be relocated at Load time, independently of 
other parts of the program and without impairing or changing the program 
Logic. CSECTs are the basic input unit to the Linkage Editor program. 


DSECT (dummy section) 

A named control section that is assembled but is not part of the object 
program. It is a convenient means of describing the Layout of a storage area 
without actually reserving storage space. 


DTF (define the file) 

A tape operating system (TOS) mnemonic for the general class of TOS file 
definition macros. For example, DTFSR stands for "define the file serial” 
and is a TOS file definition macro for sequentially organized files. BTAM 
and SAM constitute sequential access methods in an operating system with 
virtual addressing. 


ETX Cend of text) 

A character signifying the end of a data transmission. The actual bit 
configuration of this character varies with the type of terminal being 
used. ETX is also known as "end marker" (EM). 

EXCP (execute channel program) 

A macro on the physical I/O Level that allows the programmer to communicate 
with an I/0 device without using the standard DMS or TOS FCP Logic. 

FCB 

Two meanings: 

1. File Control Block - contains all information relating to a given file; 
2. Macro for generating the File Control Block. 

FIFO (first in first out) 

A queuing technique that processes information in the same sequence as it 
entered the queue. 

File 

Related records combined to form a named entity. These identifiable 
entities are called "files". For example, the following are files: 

l. Conventional input/output program data. 

2. Load modules and object module Libraries. 


3. Textual information generated and processed by the File Editor. 


foreign voLume 
In the DMS, a foreign volume is one that is not cataloged in the system. 


home address, hardware key fieLd 

Part of the track descriptor record (record 0) or data record found in 

each track of a disk. The key field contains control information concerning 
the record. It can vary in size from 1 to 255 bytes. 
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interactive job 
An interactive job (also known as a conversational job) is one that is 
initiated and run from a terminal in dialog with the user. 


I/0, LogicaL LeveL 

A type of input/output processing where the user operates on record Level 
by means of the GET and PUT macros, or of other macros. Device handling is 
effected using the OPEN and CLOSE Logic. The bLocking/debLocking of records 
as well as error recovery are also carried out by the system routines. 


I/0, physical Level 

A type of input/output processing where the user operates on device Level. 
He supplies the Command Control BLocks (CCBs) and Channel Command Words 
(CCWs) and controls the devices himself in conjunction with the EXCP macro 
(Execute Channel Program). The bLocking/debLocking of records as well as 
error recovery are also the user's responsibility. 


job 

The sum total of everything that occurs between a user's LOGON and LOGOFF 
© commands. Whether the job is already completely defined (batch mode) or 

whether the individual steps are not defined until the job is processed 

(interactive mode) is of no consequence here. 


Link name 

This is the Logical file name that provides the connection between the 
FCB (File Control BLock) macro and the job control Language (JCL), and 
between the Task File Table (TFT) and device handLing. 


Locate mode 

In Locate mode means the user requests the Location of the current record 
in the buffer area. The user is responsibLe.for transferring data to and 
from the buffer. 


move mode 
In move mode means the user specifies the Location of the record in his 
program and the system is responsible for moving it to or from the buffer. 


nuLL fiLe 
A file that is Logically empty. This file has been cataloged by the system 
and is assigned storage space by the system, but it contains no data. 


C PAM bLock, PAM page 
Contiguous memory of 2048 bytes, starting at an address divisibLe by 2048. 


priviLeged mode, program 
ALL operating system components which do not execute in processor state 
P1. The four processor states are: 


1. Pl (processor state): interprets and executes the user programs, is 
therefore also often referred to as user state. 


2. P2 (interrupt response state): performs certain functions depending 
on the interrupt status. 


3. P3 Cinterrupt control state): analyzes the cause of an interrupt, 
establishes its priority, and transfers control to the related 
interrupt handLing routines. 


4. Ρα (machine condition state: is entered whenever a machine error 
occurs. 
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procedure file 

A set of predefined operations/commands that specify a sequence to be 
performed. A procedure file may also contain data to be used as input for 
a program. The two types of procedure file are the ENTER and the DO file. 
Both can be initiated from a terminal or from a batch job. However, when 
an ENTER file is initiated, the calling task does not remain connected to 
the procedure, as it does when a DO file is initiated. The ENTER file 
becomes a background (non-interactive) task. 


PVS - Public Volume Set or pubset 
A set consisting of a number of independent public volumes (pubsets) on 
a single system. 


PVS ID 

Identification of a pubset. The fourth character of the volume serial number 
(vsn) is used for identification purposes. In the file name, this is 
indicated by means of ":x:". 


runtime parameter 

A term adopted from TOS (tape operating system) and used for parameters 
needed during TOS program execution. These parameters can be used to 
allocate devices to TOS programs, to position files, to check standard 
Labels etc. 


shareabLe fiLe 

A file that the user catalogs with the SHARE=YES operand. Files marked as 
shareable can be accessed by any user who can provide the user ID of the 

file's creator, the file name, and (if required) the appropriate password 
by which the file is protected. 


spooLin 
The transcription of input from Low-speed peripherals to temporary disk 
files. 


spooLout 
The transcription by the softvare product SPOOL of output from the system to 
relatively Low-speed devices such as printers, card punches etc. 


step 
A Logical subdivision of a job. Abnormal termination of a step in a job 
causes the next step to be executed. 


symboLic device name 

A TOS name associated with each Logical file in a TOS program and used to 
assign the actual I/O device to this file. As a ruLe, the name is six 
characters in Length , e.g. SYSOO07. This is not the same as the installation 
mnemonic for a device, which is a two-character code such as Al, assigned at 
system generation time. 
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system files (SYSOUT, SYSLST, SYSLSTnn, SYSOPT, SYSCMD, SYSDTA, SYSIPT) 
Users have only indirect access to system files; the Control System routines 
can access them directly. System files provide data and facilities 

required by the Control System functions. The two general classes of system 
files are referred to as temporary and Symbolic. Both classes are assigned 
standard names. 


Temporary system files are created and managed by routines that use the 
facilities of the job control component of BS2000. Their Logical names are: 


SYSOUT System messages that record the commands and their responses and 
are destined for output to printer or terminal. i 


SYSLST Listings such as those produced by an assembLy or Linkage Editor 
run, which are destined for output to printer. 


SYSLSTnn Listings; up to 99 system files can be specified. Each Listing 
must be assigned to a cataloged file. 


= SYSOPT files in card format, such as modules produced by an assembly run, 
which are destined for output to punch. 


These temporary system files are given temporary file names when they are 
first accessed by a user or when they are accessed by the Control System via 
OPEN. After spoolout these files are deleted and their disk space is 
restored to the system. 


Other system files managed by the system are strictly symbolic in nature. 
They never receive file names, nor do they reside on disk. SYSCMD, SYSDTA 
and SYSIPT are such symbolic files. 


SYSCMD comprises the commands issued by a user in his job. The Control 
System alone reads this file. 


SYSDTA comprises the input data for a module and is accessed by the 
RDATA macro. ; 


SYSIPT is the symbolic system input file maintained for reasons of 
compatibility with TOS. It is the TOS counterpart of the SYSDTA 
file and is accessed by the TOS macro RDCRD. 


- TM (tape mark) 
A single character on magnetic tape, preceded and followed by a gap, that 
is used to delimit data groups. In the case of 9-track tape, the bit con- 


figuration depends on the system. 


voLume seriaL number (vsn) 

A six-character number assigned to a volume at initialization time (VOLIN 
or INIT) and included in the standard volume Label for identification 
purposes. 


voLume table of contents (ντος) 


An extent which resides on a disk and contains file Labels and file address 
information. 
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